TuneFind API Reference

Overview

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 Standard API users must not cache or store API data in any form for longer than than 24 hours.

There are two versions of the TuneFind API, Standard and Premium.

The TuneFind Premium API is a paid service. In addition to the full song, show, and movie data found on TuneFind, the Premium API offers native, country- specific store links for songs. Premium API partners can use the Premium API to deeply integrate TuneFind data into their applications and monetize customer song downloads via their own affiliate memberships. Contact us at help@tunefind.com for more information about licensing the Premium API.

The TuneFind Standard API is a free service. The Standard API allows developers to enhance their services with song, show, and movie data from TuneFind. Store links are routed through TuneFind's servers. To use the Standard API, create a TuneFind account, confirm your email address, and apply now. You'll get immediate access to TuneFind data through the previous year. When we verify your application adheres to our API Terms of Use, we'll grant you access to real-time data.

Endpoint and Versioning

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://www.tunefind.com/api/v1/

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.

Authentication

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://www.tunefind.com/api/v1/show/alias

Encoding

All responses are provided in the UTF-8 character set and default to JSON encoding.

https://www.tunefind.com/api/v1/show/alias

A client may also explicitly choose JSON or XML encoding either via an Accept request header.

FormatAccept Header
JSONapplication/json
XMLapplication/xml

HTTP

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.

Data Types

  • Dates are represented in ISO 8601 format.
  • All dates are in UTC.
  • Country codes are represented in ISO 3166 format.
  • Numeric days of the week start with Monday as 0 and end with Sunday as 6.
  • Confidence codes are "high" and "medium". We don't show low confidence data in the API, though this data may be visible on TuneFind.com.

Response Codes and Errors

Success and failure are communicated as HTTP response codes:

  • 200: Success
  • 400: Bad Request
  • 401: Unauthorized
  • 403: Forbidden
  • 404: Resource Not Found
  • 405: Method Not Allowed
  • 500: Application Error
  • 503: Over Rate Limit

Rate Limiting

The default rate limit for API clients is one request per second. Clients requesting resources more frequently may see HTTP 503 responses. Please contact us if you require a higher limit.

Caching

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, Standard 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.

Pagination

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://www.tunefind.com/api/v1/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://www.tunefind.com/api/v1/show?limit=10&offset=20

Date Filtering

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://www.tunefind.com/api/v1/show?updated=2010-01-01T00%3A00%3A00%2B00%3A00

Date filtering may be combined with pagination.

Debugging

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.

Store Data

  • Premium API store IDs are "itunes" and "amazon".
  • Standard API store IDs are "itunes-tunefind" and "amazon-tunefind".
  • Standard API users must append one of listed country codes to generate a complete URL, for example "&country=US". If a country is not listed, a link to a store in that country is not available. Contact us for more information.
  • Song data will always include either a 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.

Methods

show

https://www.tunefind.com/api/v1/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://www.tunefind.com/api/v1/show/alias"
  }
]

movie

https://www.tunefind.com/api/v1/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://www.tunefind.com/api/v1/movie/ghosts-of-girlfriends-past"
  }
]

artist

https://www.tunefind.com/api/v1/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://www.tunefind.com/api/v1/artist/lady-gaga"
  }
]

artist/<artist-id>

https://www.tunefind.com/api/v1/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://www.tunefind.com/api/v1/show/gossip-girl/season-2?debug=json"
      }
    ],
    "movies": [
    ]
  }
]

show/<show-id>

https://www.tunefind.com/api/v1/show/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://www.tunefind.com/api/v1/show/alias/season-1",
    "episode_count": "17",
    "song_count": "24"
  }
]

show/<show-id>/season-<season-number>

https://www.tunefind.com/api/v1/show/alias/season-1

"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://www.tunefind.com/api/v1/show/alias/season-1/286"
    "song_count": "2"
  }
]

show/<show-id>/season-<season-number>/<episode-id>
movie/<movie-id>

https://www.tunefind.com/api/v1/show/alias/season-1/286

"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",
    "artist": {
      "id": "cat-stevens",
      "name": "Cat Stevens"
    },
    "stores": [
      {
        "id": "itunes",
        "country": "US",
        "album_id": "1109868",
        "album_url": "https://itunes.apple.com/ca/album/trouble/id1109868",
        "song_id": "1109778",
        "song_url": "https://itunes.apple.com/ca/album/trouble/id1109868?i=1109778"
      },
      {
        "id": "itunes-tunefind",
        "countries": ["US"],
        "url": "http://www.tunefind.com/forward/song/762?store=itunes"
      },
      {
        "id": "amazon",
        "country": "US",
        "search_url": "http://www.amazon.com/s?ie=UTF8&index=digital-music&keywords=Cat+Stevens+Trouble"
      },
      {
        "id": "amazon-tunefind",
        "countries": ["CA", "DE", "FR", "UK", "US"],
        "url": "http://www.tunefind.com/forward/song/762?store=amazon"
      },
    ]
  }
]

Document History

  • 2013-03-16: Standard and Premium API levels
  • 2013-03-03: added episode_count and song_count to season list and song_count to episode list
  • 2012-12-22: Amazon URLs were improperly named "song_url" instead of "search_url"; both will be available transitionally until 2013-03-01 at which point "song_url" will only be present for exact matches
  • 2011-09-20: added movie air date
  • 2011-09-04: API v1 new artist methods; change documentation to JSON
  • 2010-07-26: API v1 finalized
  • 2010-07-19: API v1 draft 2
  • 2010-07-12: API v1 draft 1
  • 2010-07-02: first revision