This document describes the Tunefind REST API. The API provides methods for reading most of the data found on Tunefind.com. All API requests are secured, authenticated, and rate-limited as described below. Use of our data is subject to the Tunefind Terms of Use and Tunefind API Terms of Use. Per these terms users must not cache or store API data in any form for longer than than 24 hours.
Interested in subscribing to our API? View our plans and pricing.
View your current subscription level and invoices on your Subscription Dashboard.
The Tunefind API is offered via HTTPS only. The API version is explicitly denoted in the endpoint URL. The current endpoint as of this writing is:
https://[API-USER-ID].api.tunefind.com/api/v2/
We may add fields, add methods, and fix API bugs without incrementing the version number. However, we will only make structural changes, field definition changes, or method changes along with a version number update.
All API requests must be authenticated via HTTP Basic Authentication. In combination with mandatory HTTPS, this scheme provides for simple and secure client access. An example using curl:
curl -u user:pass https://[API-USER-ID].api.tunefind.com/api/v2/show/alias
All responses are provided in the UTF-8 character set and default to JSON encoding.
https://[API-USER-ID].api.tunefind.com/api/v2/show/alias
A client may also explicitly choose JSON or XML encoding either via an Accept request header.
| Format | Accept Header |
|---|---|
| JSON | application/json |
| XML | application/xml |
We ask that clients support gzip encoding and make requests with an "Accept-Encoding: gzip" header. If possible we will gzip the response, indicated by a "Content-Encoding: gzip" response header.
Requests may be made in either HTTP/1.0 or HTTP/1.1. We support persistent connections via HTTP/1.1 keepalives.
Success and failure are communicated as HTTP response codes:
All plans are rate limited as described on our plans and pricing. Please contact us if you require a higher limit.
We encourage API developers to cache the results of API calls locally via memcached or similar mechanisms. This both alleviates load on the Tunefind service and speeds up your application. We recommend caching data for 24 hours for episodes and movies over one week old and for 1 hour for newer shows.
Per the Tunefind API Terms of Use, API users must not cache or store API data in any form for longer than than 24 hours. Failure to meet this requirement will result in immediate account termination and possible legal action.
Premium API users may cache or store data as specified in their contract. Contact help@tunefind.com for more information.
List methods return a maximum of 1000 resources at a time. To page through results, specify a positive zero-indexed integer offset as a GET parameter:
https://[API-USER-ID].api.tunefind.com/api/v2/show?offset=1000
Some API methods are not likely to return more than 1000 items in the foreseeable future. However, robust clients will attempt to retrieve additional results if a method returns 1000 items.
Requests beyond the available data offset will return an empty result set.
To change the default paging size, specify a positive integer limit as a GET parameter:
https://[API-USER-ID].api.tunefind.com/api/v2/show?limit=10&offset=20
List methods support an optional "updated" GET parameter. When provided, only results updated after this date will be listed. The date format is ISO 8601.
https://[API-USER-ID].api.tunefind.com/api/v2/show?updated=2010-01-01T00%3A00%3A00%2B00%3A00
Date filtering may be combined with pagination.
Adding a "debug=xml" or "debug=json" GET parameter forces the corresponding encoding and pretty-prints the result in HTML. These are intended for browser consumption; links in the XML encoding are clickable.
song_url or a search_url for a store.
It may also include a song_id, artist_url, artist_id, album_url, and album_id.showhttps://[API-USER-ID].api.tunefind.com/api/v2/show "shows": [ { "id": "alias", "name": "Alias", "date_updated": "2010-01-01T00:00:00+00:00", "tunefind_url": "http://www.tunefind.com/show/alias", "tunefind_api_url": "https://[API-USER-ID].api.tunefind.com/api/v2/show/alias" } ]
moviehttps://[API-USER-ID].api.tunefind.com/api/v2/movie "movies": [ { "id": "ghosts-of-girlfriends-past", "name": "Ghosts of Girlfriends Past", "air_date": 2009-04-30T00:00:00+00:00", "date_updated": "2010-01-01T00:00:00+00:00", "tunefind_url": "http://www.tunefind.com/movie/ghosts-of-girlfriends-past", "tunefind_api_url": "https://[API-USER-ID].api.tunefind.com/api/v2/movie/ghosts-of-girlfriends-past" } ]
artisthttps://[API-USER-ID].api.tunefind.com/api/v2/artist "artists": [ { "id": "lady-gaga", "name": "Lady GaGa", "date_updated": "2010-01-01T00:00:00+00:00", "tunefind_url": "http://www.tunefind.com/artist/lady-gaga", "tunefind_api_url": "https://[API-USER-ID].api.tunefind.com/api/v2/artist/lady-gaga" } ]
artist/<artist-id>https://[API-USER-ID].api.tunefind.com/api/v2/artist/lady-gaga "songs": [ { "id": "11870", "name": "Paparazzi", "date_updated": "2010-01-01T00:00:00+00:00", "tunefind_url": "http://www.tunefind.com/song/11870", "stores": [ { "id": "itunes", "country": "US", "album_id": "294084085", "album_url": "https://itunes.apple.com/us/album/paparazzi/id294084085?uo=4", "song_id": "294084106", "song_url": "https://itunes.apple.com/us/album/paparazzi/id294084085?i=294084106&uo=4" }, { "id": "itunes-tunefind", "countries": ["US"], "url": "http://www.tunefind.com/forward/song/11870?store=itunes" }, { "id": "amazon", "country": "US", "search_url": "http://www.amazon.com/s?ie=UTF8&index=digital-music&keywords=Lady+GaGa+Paparazzi" }, { "id": "amazon-tunefind", "countries": ["CA", "DE", "FR", "UK", "US"], "url": "http://www.tunefind.com/forward/song/11870?store=amazon" }, ], "shows": [ { "id": "gossip-girl", "number": "2", "episode_id": "3229", "tunefind_url": "http://www.tunefind.com/show/gossip-girl/season-2", "tunefind_api_url": "https://[API-USER-ID].api.tunefind.com/api/v2/show/gossip-girl/season-2?debug=json" } ], "movies": [ ] } ]
show/<show-id>https://[API-USER-ID].api.tunefind.com/api/v2/show/alias { "show_name" : "Alias", "seasons" : [ { "id": "100", "number": "1", "date_updated": "2010-01-01T00:00:00+00:00", "tunefind_url": "http://www.tunefind.com/show/alias/season-1", "tunefind_api_url": "https://[API-USER-ID].api.tunefind.com/api/v2/show/alias/season-1", "episode_count": "17", "song_count": "24" } ] }
show/<show-id>/season-<season-number>https://[API-USER-ID].api.tunefind.com/api/v2/show/alias/season-1 { "season_name" : "Season 1", "show_name" : "Alias", "episodes" : [ { "id": "286", "name": "Truth Be Told", "number": "1", "air_date": "2001-09-30T00:00:00+00:00", "date_updated": "2010-01-01T00:00:00+00:00", "tunefind_url": "http://www.tunefind.com/show/alias/season-1/286", "tunefind_api_url": "https://[API-USER-ID].api.tunefind.com/api/v2/show/alias/season-1/286" "song_count": "2" } ] }
show/<show-id>/season-<season-number>/<episode-id>movie/<movie-id>https://[API-USER-ID].api.tunefind.com/api/v2/show/alias/season-1/286 { "episode_name" : "Truth Be Told", "name" : "Alias", "season_name" : "Season 1", "songs" : [ { "id": "762", "name": "Trouble", "confidence": "high", "scene": "Syd flashes back to her recruitment/Soothing Danny about her real job.", "date_updated": "2010-01-01T00:00:00+00:00", "tunefind_url": "http://www.tunefind.com/song/762", "tunefind_api_url": "https://[API-USER-ID].api.tunefind.com/api/v2/show/alias/season-1/286/762", "preview_url": "http://a289.phobos.apple.com/us/r1000/113/Music/90/83/ca/mzm.jnrcedyd.aac.p.m4a", "artist": { "id": "cat-stevens", "name": "Cat Stevens", "tunefind_api_url": "https://[API-USER-ID].api.tunefind.com/api/v2/artist/cat-stevens", "tunefind_url": "http://www.tunefind.com/artist/cat-stevens" }, "stores": [ { "id": "itunes-tunefind", "countries": ["US"], "url": "http://www.tunefind.com/forward/song/762?store=itunes" }, { "id": "amazon-tunefind", "countries": ["CA", "DE", "FR", "UK", "US"], "url": "http://www.tunefind.com/forward/song/762?store=amazon" }, { "id": "applemusic-tunefind", "countries": ["US"], "url": "http://www.tunefind.com/forward/song/762?store=applemusic" } ] } ] }