Search API 官方文档可以用了查看自己的app

Search API

October 24, 2012 - HTTPS is now supported for Search and Lookup requests. Please update your processes to use https or follow a redirect from http.

Overview

The Search API allows you to place search fields in your website to search for content within the iTunes Store, App Store, iBookstore and Mac App Store. You can search for a variety of content; including apps, ebooks, movies, podcasts, music, music videos, audiobooks, and TV shows. You can also call an ID-based lookup request to create mappings between your content library and the digital catalog. Terms and conditions apply.

The Affiliate Program allows you to earn a commission on qualifying revenue generated by clicks initiated from your website or app into the iTunes Store, App Store, iBookstore, and Mac App Store. For more information on the Affiliate Program, see http://www.apple.com/itunes/affiliates.

Searching

To search for content from a field in your website and display the results in your website, you must create a search field that passes a fully-qualified URL content request to the iTunes Store, parse the JavaScript Object Notation (JSON) format returned from the search, and display the results in your website.

The fully-qualified URL must have the following format:

https://itunes.apple.com/search?parameterkeyvalue

Where parameterkeyvalue can be one or more parameter key and value pairs indicating the details of your query.

To construct a parameter key and value pair, you must concatenate each parameter key with an equal sign (=) and a value string. For example:key1=value1. To create a string of parameter key and value pairs, you must concatenate each pair using an ampersand (&). For example:

key1=value1&key2=value2&key3=value3

Note: When creating search fields and scripts for your website, you should use dynamic script tags for your xmlhttp script call requests. For example:

<script src="https://.../search?parameterkeyvalue&callback="{name of JavaScript function in webpage}"/>

The following table defines the parameter keys and values you can specify to search for content within the iTunes Store, App Store, iBookstore and Mac App Store:

Parameter Key

Description

Required

Values

term

The URL-encoded text string you want to search for. For example: jack+johnson.

Any URL-encoded text string.

Note: URL encoding replaces spaces with the plus (+) character and all characters except the following are encoded: letters, numbers, periods (.), dashes (-), underscores (_), and asterisks (*).

country

The two-letter country code for the store you want to search. The search uses the default store front for the specified country. For example: US.

The default is US.

See http://en.wikipedia.org/wiki/ ISO_3166-1_alpha-2 for a list of ISO Country Codes.

media

The media type you want to search for. For example: movie.

The default is all.

movie, podcast, music, musicVideo, audiobook, shortFilm, tvShow, software, ebook, all

entity

The type of results you want returned, relative to the specified media type. For example: movieArtist for a movie media type search.

The default is the track entity associated with the specified media type.

The following entities are available for each media type:

movie	movieArtist, movie
podcast	podcastAuthor, podcast
music	musicArtist, musicTrack, album, musicVideo, mix, song Please note that "musicTrack" can include both songs and music videos in the results
musicVideo	musicArtist, musicVideo
audiobook	audiobookAuthor, audiobook
shortFilm	shortFilmArtist, shortFilm
tvShow	tvEpisode, tvSeason
software	software, iPadSoftware, macSoftware
ebook	ebook
all	movie, album, allArtist, podcast, musicVideo, mix, audiobook, tvSeason, allTrack

attribute

The attribute you want to search for in the stores, relative to the specified media type. For example, if you want to search for an artist by name specify entity=allArtist&attribute=allArtistTerm.

In this example, if you search for term=maroon, iTunes returns "Maroon 5" in the search results, instead of all artists who have ever recorded a song with the word "maroon" in the title.

The default is all attributes associated with the specified media type.

The following attributes are available for each media type:

movie	actorTerm, genreIndex, artistTerm, shortFilmTerm, producerTerm, ratingTerm, directorTerm, releaseYearTerm, featureFilmTerm, movieArtistTerm, movieTerm, ratingIndex, descriptionTerm
podcast	titleTerm, languageTerm, authorTerm, genreIndex, artistTerm, ratingIndex, keywordsTerm, descriptionTerm
music	mixTerm, genreIndex, artistTerm, composerTerm, albumTerm, ratingIndex, songTerm
musicVideo	genreIndex, artistTerm, albumTerm, ratingIndex, songTerm
audiobook	titleTerm, authorTerm, genreIndex, ratingIndex
shortFilm	genreIndex, artistTerm, shortFilmTerm, ratingIndex, descriptionTerm
software	softwareDeveloper
tvShow	genreIndex, tvEpisodeTerm, showTerm, tvSeasonTerm, ratingIndex, descriptionTerm
all	actorTerm, languageTerm, allArtistTerm, tvEpisodeTerm, shortFilmTerm, directorTerm, releaseYearTerm, titleTerm, featureFilmTerm, ratingIndex, keywordsTerm, descriptionTerm, authorTerm, genreIndex, mixTerm, allTrackTerm, artistTerm, composerTerm, tvSeasonTerm, producerTerm, ratingTerm, songTerm, movieArtistTerm, showTerm, movieTerm, albumTerm

callback

The name of the Javascript callback function you want to use when returning search results to your website. For example: wsSearchCB.

Y, for cross-site searches

wsSearchCB

limit

The number of search results you want the iTunes Store to return. For example: 25.

The default is 50.

1 to 200

lang

The language, English or Japanese, you want to use when returning search results. Specify the language using the five-letter codename. For example: en_us.

The default is en_us (English).

en_us, ja_jp

version

The search result key version you want to receive back from your search.

The default is 2.

1, 2

explicit

A flag indicating whether or not you want to include explicit content in your search results.

The default is Yes.

Yes, No

Notes

It is critical to encode your URLs correctly in order to be commissioned for affiliate links. Notes on affiliate encoding raw links can be found in theAdvanced Affiliate Linking document.
To improve response times, minimize the number of search results the Search API returns by specifying an appropriate value for the limit parameter key.
Large websites should set up caching logic for the search and lookup requests sent to the Search API. For an illustration, see Caching Architecture later in this document.

Search Examples

The following are examples of fully-qualified URLs for specific search requests:

To search for all Jack Johnson audio and video content (movies, podcasts, music, music videos, audiobooks, short films, and tv shows), your URL would look like the following:

https://itunes.apple.com/search?term=jack+johnson
To search for all Jack Johnson audio and video content and return only the first 25 items, your URL would look like the following:

https://itunes.apple.com/search?term=jack+johnson&limit=25
To search for only Jack Johnson music videos, your URL would look like the following:

https://itunes.apple.com/search?term=jack+johnson&entity=musicVideo
To search for all Jim Jones audio and video content and return only the results from the Canada iTunes Store, your URL would look like the following:

https://itunes.apple.com/search?term=jim+jones&country=ca
To search for applications titled "Yelp" and return only the results from the United States iTunes Store, your URL would look like the following:

https://itunes.apple.com/search?term=yelp&country=us&entity=software

Lookup Examples

You can also create a lookup request to search for content in the stores based on iTunes IDs, UPCs/ EANs, and All Music Guide (AMG) IDs. ID-based lookups are faster and contain fewer false-positive results.

The following are examples of fully-qualified URLs for specific lookup requests:

Look up Jack Johnson by iTunes artist ID:

https://itunes.apple.com/lookup?id=909253
Look up Yelp Software application by iTunes ID:

https://itunes.apple.com/lookup?id=284910350
Look up Jack Johnson by AMG artist ID:

https://itunes.apple.com/lookup?amgArtistId=468749
Look up multiple artists by their AMG artist IDs:

https://itunes.apple.com/lookup?amgArtistId=468749,5723
Look up all albums for Jack Johnson:

https://itunes.apple.com/lookup?id=909253&entity=album
Look up multiple artists by their AMG artist IDs and get each artist's top 5 albums:

https://itunes.apple.com/lookup?amgArtistId=468749,5723&entity=album&limit=5
Look up multiple artists by their AMG artist IDs and get each artist's 5 most recent songs:

https://itunes.apple.com/lookup?amgArtistId=468749,5723&entity=song&limit=5&sort=recent
Look up an album or video by its UPC:

https://itunes.apple.com/lookup?upc=720642462928
Look up an album by its UPC, including the tracks on that album:

https://itunes.apple.com/lookup?upc=720642462928&entity=song
Look up an album by its AMG Album ID:

https://itunes.apple.com/lookup?amgAlbumId=15175,15176,15177,15178,15183,15184,15187,1519,15191,15195,15197,15198
Look up a Movie by AMG Video ID:

https://itunes.apple.com/lookup?amgVideoId=17120
Look up a book by its 13 digit ISBN:

https://itunes.apple.com/lookup?isbn=9780316069359

Understanding Search Results

The Search API returns your search results in JavaScript Object Notation (JSON) format. JSON is built on two structures:

A collection of name/value pairs, also known as an object; this concept is similar to a Java Map object, a Javascript Dictionary, or a Pearl/Ruby hash. An object is an unordered set of name/value pairs, beginning with a left brace ( { ) and ending with a right brace ( } ). Each name is surrounded by double-quotes and followed by a colon ( : ); the name/value pairs are separated by commas ( , ).
An ordered list of values, also known as an array. An array is an ordered collection of values, beginning with a left bracket ( [ ) and ending with a right bracket ( ] ). Values are separated by commas ( , ).

All JSON results are encoded as UTF-8. For more information on JSON, please see http://www.json.org.

The following example displays the JSON results for a song in the iTunes Store:

{"wrapperType":"track",

 "kind":"song",

 "artistId":909253,

 "collectionId":120954021,

 "trackId":120954025,

 "artistName":"Jack Johnson",

 "collectionName":"Sing-a-Longs and Lullabies for the Film Curious George",

 "trackName":"Upside Down",

 "collectionCensoredName":"Sing-a-Longs and Lullabies for the Film Curious George",

 "trackCensoredName":"Upside Down",

 "artistViewUrl":"https://itunes.apple.com/WebObjects/MZStore.woa/wa/viewArtist?id=909253",

 "collectionViewUrl":"https://itunes.apple.com/WebObjects/MZStore.woa/wa/viewAlbum?i=120954025&id=120954021&s=143441",

 "trackViewUrl":"https://itunes.apple.com/WebObjects/MZStore.woa/wa/viewAlbum?i=120954025&id=120954021&s=143441",

 "previewUrl":"http://a1099.itunes.apple.com/r10/Music/f9/54/43/mzi.gqvqlvcq.aac.p.m4p",

 "artworkUrl60":"http://a1.itunes.apple.com/r10/Music/3b/6a/33/mzi.qzdqwsel.60x60-50.jpg",

 "artworkUrl100":"http://a1.itunes.apple.com/r10/Music/3b/6a/33/mzi.qzdqwsel.100x100-75.jpg",

 "collectionPrice":10.99,

 "trackPrice":0.99,

 "collectionExplicitness":"notExplicit",

 "trackExplicitness":"notExplicit",

 "discCount":1,

 "discNumber":1,

 "trackCount":14,

 "trackNumber":1,

 "trackTimeMillis":210743,

 "country":"USA",

 "currency":"USD",

 "primaryGenreName":"Rock"}

The following table defines the JSON result keys and values:

Result Key	Description	Returned	Return Values and Examples
wrapperType	The name of the object returned by the search request.	Y	track, collection, artist For example: track.
*explicitness	The Recording Industry Association of America (RIAA) parental advisory for the content returned by the search request. For more information, seehttp://itunes.apple.com/WebObjects/MZStore.woa/wa/parentalAdvisory.	Y	explicit (explicit lyrics, possibly explicit album cover), cleaned (explicit lyrics "bleeped out"), notExplicit (no explicit lyrics) For example: "trackExplicitness":"notExplicit".
kind	The kind of content returned by the search request.	Y	book, album, coached-audio, feature-movie, interactive- booklet, music-video, pdf podcast, podcast-episode, software-package, song, tv- episode, artist For example: song.
trackName	The name of the track, song, video, TV episode, and so on returned by the search request.	Y	For example: "Banana Pancakes".
artistName	The name of the artist returned by the search request.	Y	For example: Jack Johnson.
collectionName	The name of the album, TV season, audiobook, and so on returned by the search request.	Y	For example: "In Between Dreams".
*censoredName	The name of the album, TV season, audiobook, and so on returned by the search request, with objectionable words 'd out. Note:* Artist names are never censored.	Y	For example: "S**t Happens".
artworkUrl100, artworkUrl60	A URL for the artwork associated with the returned media type, sized to 100x100 pixels or 60x60 pixels.	Only returned when artwork is available	For example: "http:// a1.itunes.apple.com/jp/r10/Music/ y2005/m06/d03/h05/ s05.oazjtxkw.100x100-75.jpg".
*viewURL	A URL for the content associated with the returned media type. You can click the URL to view the content in the iTunes Store.	Y	For example: "http:// itunes.apple.com/WebObjects/ MZStore.woa/wa/viewAlbum? i=68615807&id=68615813&s=1434 62".
previewUrl	A URL referencing the 30-second preview file for the content associated with the returned media type. .	Only returned when media type is track	For example: "http:// a392.itunes.apple.com/jp/r10/ Music/y2005/m06/d03/h05/s05.zdzqlufu.p.m4p".
trackTimeMillis	The returned track's time in milliseconds.	Only returned when media type is track

Caching Architecture

Legal

Affiliate may use certain promotional content as may be provided by Apple, including previews of songs and music videos, album art, and App icons ("Promo Content"), for the purposes of promoting the subject of the Promo Content; provided such Promo Content: (i) is placed only on pages that promote the content on which the Promo Content is based; (ii) is proximate to a "Download on iTunes" or "Available on the App Store" badge (as approved by Apple) that acts as a link directly to pages within iTunes or the App Store where consumers can purchase the promoted content; (iii) includes attribution indicating the Promo Content was "provided courtesy of iTunes" if such Promo Content includes song or music video previews; (iv) is streamed only, and not downloaded, saved, cached, or synchronized with video, if such Promo Content includes song or music video previews; (v) is not used for independent entertainment value apart from its promotional purpose; and (vi) is not used to promote any other goods or services. Affiliate acknowledges that Apple provides the Promo Content "as is," and disclaims any and all representations or warranties, including, but not limited to, non-infringement. Affiliate shall forward any claims received in connection with the Promo Content to Apple immediately upon receipt, and will remove any Promo Content immediately upon request from Apple.

This agreement and your use of Promo Content are governed by California law.