[iOS] iTunes Search API

iTunes Search API

iTunes Search API는 iTunes Store 및 Apple Books Store 내에서 콘텐츠를 검색할 수 있는 API입니다.
AppStore 구현을 하며 iTunes Search API를 사용하게 되어 학습 목적으로 글을 작성합니다.

검색

웹 사이트의 필드에서 콘텐츠를 검색하고 웹 사이트에 결과를 표시하려면 정규화된 URL 콘텐츠 요청을 iTunes Store로 전달하는 검색 필드를 생성하여야 합니다.

정규화된 URL의 형식은 다음과 같아야 합니다.

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

여기서 parameterkeyvalue는 쿼리의 세부 정보를 나타내는 하나 이상의 매개 변수 키 및 값 쌍일 수 있습니다.

매개변수 키와 값 쌍을 구성하려면 각 매개변수 키를 = 및 값 문자열로 연결해야 합니다.

key1=value1

매개변수 키 및 값 쌍의 문자열을 생성하려면 &를 사용하여 각 쌍을 연결해야 합니다.

key1=value1&key2=value2&key3=value3

 

ParameterKey

콘텐츠를 검색하기 위하여 지정할 수 있는 매개변수 키와 값을 설명하겠습니다.

term

검색하려는 URL의 인코딩 된 텍스트 문자열입니다.
URL 인코딩은 공백을 +로 바꾸고 문자, 숫자, ., -, _, *를 제외한 모든 문자가 인코딩 됩니다.

country

검색하려는 스토어의 두 자리 국가 코드입니다.
검색은 지정된 국가에 대한 기본 스토어 정보를 사용합니다.

국가 코드 목록은 http://en.wikipedia.org/wiki/ ISO_3166-1_alpha-2에서 확인할 수 있습니다.

한국은 KR 이니까 country=KR로 지정해주면 되겠네요!

media

검색하려는 미디어 유형입니다.
movie, podcast, music, musicVideo, audiobook, shortFilm, tvShow, software, ebook, all을 값으로 입력할 수 있습니다.

앱스토어를 구현하기 위해서는 software가 필요하겠네요.

entity

지정된 미디어 유형과 관련하여 반환하려는 결과 유형입니다.
software의 값에는 software, iPadSoftware, macSoftware가 있습니다.

attribute

지정된 미디어 유형과 관련하여 스토어에서 검색하려는 속성입니다.
기본값은 지정된 미디어 유형과 관련된 모든 속성입니다.

software 유형에 대해 softwareDeveloper 속성을 사용할 수 있습니다.

all 유형에 대해선 languageTerm, releaseYearTerm, titleTerm, ratingIndex, keywordsTerm, descriptionTerm, authorTerm, mixTerm, ratingTerm 등의 속성을 사용할 수 있습니다.

callback

웹 사이트에 검색 결과를 반환할 때 사용할 자바스크립트 콜백 함수의 이름입니다.
교차 사이트 검색용으로 wsSearchCB 값을 사용할 수 있습니다.

limit

iTunes Store에서 반환할 검색 결과의 수를 제한합니다.
기본 값은 50이며 1에서 200의 값으로 제한할 수 있습니다.

lang

검색 결과를 반환할 때 사용할 언어를 5자리 코드명을 사용하여 지정합니다.
기본값은 en_us입니다.

version

검색에서 다시 수신하려는 검색 결과 키 버전입니다.
기본값은 2입니다.

explicit

검색 결과에 명시적 콘텐츠를 포함할지 여부를 나타내는 플래그입니다.
기본값은 Yes입니다.

 

검색 예시

다음은 특정 검색 요청에 대한 정규화된 URL의 예입니다.

모든 Jack Johnson 콘텐츠를 검색하는 URL은 다음과 같습니다.

https://itunes.apple.com/search?term=jack+johnson

모든 Jack Johnson 콘텐츠를 검색하고 처음 25개 항목만 반환하려면 URL은 다음과 같습니다.

https://itunes.apple.com/search?term=jack+johnson&limit=25

Jack Johnson 뮤직 비디오만 검색하려면 URL은 다음과 같습니다.

https://itunes.apple.com/search?term=jack+johnson&entity=musicVideo

모든 Jim Jones 콘텐츠를 검색하고 Canada iTunes Store의 결과만 반환하려면 URL은 다음과 같습니다.

https://itunes.apple.com/search?term=jim+jones&country=ca

 

조회 예시

iTunes ID, UPC/EAN, AMG(All Music Guide) ID를 기반으로 스토어에서 콘텐츠를 검색하기 위한 조회 요청을 생성할 수도 있습니다.
ID 기반 조회는 더 빠르고 오탐 결과가 더 적습니다.

다음은 특정 조회 요청에 대한 정규화된 URL의 예입니다.

ID로 Jack Johnson 조회

https://itunes.apple.com/lookup?id=909253

AMG 아티스트 ID로 Jack Johnson 조회

https://itunes.apple.com/lookup?amgArtistId=468749

AMG 아티스트 ID로 여러 아티스트 조회

https://itunes.apple.com/lookup?amgArtistId=468749,5723

Jack Johnson의 모든 앨범 조회

https://itunes.apple.com/lookup?id=909253&entity=album

UPC로 앨범 또는 비디오 조회

https://itunes.apple.com/lookup?upc=720642462928

13자리 ISBN으로 책 조회

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

 

검색 결과

API는 검색 결과를 JSON 형식으로 반환합니다.

JSON은 객체와 배열 두 가지 구조를 기반으로 합니다.
객체는 {로 시작하여 }로 끝나는 이름/값 쌍의 정렬되지 않은 집합입니다.
각 이름은 ""로 묶이고 그 뒤에 :이 옵니다. 이름/값 쌍은 ,로 구분됩니다.
배열은 [로 시작하여 ]로 끝나는 정렬된 값 모음입니다. 값은 ,로 구분됩니다.

모든 JSON 결과는 UTF-8로 인코딩 됩니다.

이제 JSON 결과 키와 값을 설명하겠습니다.

wrapperType

검색 요청에서 반환된 개체의 이름입니다.
반환 값의 예시로는 track, collection, artistFor이 있습니다.

kind

검색 요청에 의해 반환된 콘텐츠의 종류입니다.
book, pdf, software-package 등과 같은 값이 반환됩니다.

artworkUrl100, artworkUrl60

반환된 미디어 유형과 관련된 아트웍의 URL로, 크기는 100x100 픽셀 또는 60x60픽셀입니다. 아트웍이 있는 경우에만 반환됩니다.

*viewURL

반환된 미디어 유형과 연결된 콘텐츠의 URL입니다.
URL을 클릭하여 iTunes Store에서 콘텐츠를 볼 수 있습니다.

 

---

 

• iTunes Search API