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

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 below. If you have not yet signed up for the API, [ENDPOINT] will appear instead of your actual endpoint hostname. Reload this page after you've signed up for your URL.

https://[ENDPOINT].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.

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://[ENDPOINT].api.tunefind.com/api/v2/show/alias

Encoding

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

https://[ENDPOINT].api.tunefind.com/api/v2/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

Response Codes and Errors

Success and failure are communicated as HTTP response codes:

Rate Limiting

All plans are rate limited as described on our plans and pricing. 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, 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://[ENDPOINT].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://[ENDPOINT].api.tunefind.com/api/v2/show?limit=10&offset=20

Date Filtering

show, movie and artist 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://[ENDPOINT].api.tunefind.com/api/v2/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

Methods

show

https://[ENDPOINT].api.tunefind.com/api/v2/show

"shows": [
  {
    "id": "alias",
    "name": "Alias",
    "date_updated": "2010-01-01T00:00:00+00:00",
    "tunefind_url": "https://www.tunefind.com/show/alias",
    "tunefind_api_url": "https://[ENDPOINT].api.tunefind.com/api/v2/show/alias"
  }
]

movie

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

artist

https://[ENDPOINT].api.tunefind.com/api/v2/artist

"artists": [
  {
    "id": "lady-gaga",
    "name": "Lady GaGa",
    "date_updated": "2010-01-01T00:00:00+00:00",
    "tunefind_url": "https://www.tunefind.com/artist/lady-gaga",
    "tunefind_api_url": "https://[ENDPOINT].api.tunefind.com/api/v2/artist/lady-gaga"
  }
]

artist/<artist-id>

https://[ENDPOINT].api.tunefind.com/api/v2/artist/lady-gaga

"songs": [
  {
    "id": "11870",
    "name": "Paparazzi",
    "date_updated": "2010-01-01T00:00:00+00:00",
    "tunefind_url": "https://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": "https://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": "https://www.tunefind.com/forward/song/11870?store=amazon"
      },
    ],
    "shows": [
      {
        "id": "gossip-girl",
        "number": "2",
        "episode_id": "3229",
        "tunefind_url": "https://www.tunefind.com/show/gossip-girl/season-2",
        "tunefind_api_url": "https://[ENDPOINT].api.tunefind.com/api/v2/show/gossip-girl/season-2?debug=json"
      }
    ],
    "movies": [
    ]
  }
]

show/<show-id>

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

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

https://[ENDPOINT].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": "https://www.tunefind.com/show/alias/season-1/286",
      "tunefind_api_url": "https://[ENDPOINT].api.tunefind.com/api/v2/show/alias/season-1/286"
      "song_count": "2"
    }
  ]
}

trending/song/now

https://[ENDPOINT].api.tunefind.com/api/v2/trending/song/now
{
  "songs": [
    {
      "rank": 1,
      "song": {
        "id": 134143,
        "name": "You Belong to Me",
        "date_updated": "2017-10-13T00:00:00+00:00",
        "tunefind_url": "https://www.tunefind.com/song/134143/0",
        "stores": [
          {
            "id": "itunes-tunefind",
            "countries": ["US"],
            "url": "https://www.tunefind.com/forward/song/134143?store=itunes"
          },
          ...
        ],
        "shows": [
          {
            "id": "riverdale",
            "season_number": 2,
            "episode_number": 1,
            "episode_id": 53256,
            "tunefind_url": "https://www.tunefind.com/song/134143/176721",
            "tunefind_api_url": "https://[ENDPOINT].api.tunefind.com/api/v2/api/v2/show/riverdale/season-2/53256/134143"
          },
          ...
        ],
        "movies": []
      },
      "artist": {
        "id": "cat-pierce",
        "name": "Cat Pierce",
        "date_updated": "2017-10-13T00:00:00+00:00",
        "tunefind_url": "https://www.tunefind.com/artist/cat-pierce",
        "tunefind_api_url": "https://[ENDPOINT].api.tunefind.com/api/v2/api/v2/artist/cat-pierce"
      }
    },
    {
      "rank": 2,
      "song": {
        "id": 131882,
        "name": "Aquarius Apocalyptic",
        "date_updated": "2017-10-14T00:00:00+00:00",
        "tunefind_url": "https://www.tunefind.com/song/131882/0",
        "stores": [
          {
            "id": "spotify-tunefind",
            "countries": ["US"],
            "url": "https://www.tunefind.com/forward/song/131882?store=spotify"
          },
          ...
        ],
        "shows": [
          {
            "id": "supergirl",
            "season_number": 2,
            "episode_number": 22,
            "episode_id": 47636,
            "tunefind_url": "https://www.tunefind.com/song/131882/173481",
            "tunefind_api_url": "https://[ENDPOINT].api.tunefind.com/api/v2/api/v2/show/supergirl/season-2/47636/131882"
          },
          ...
        ],
        "movies": []
      },
      "artist": {
        "id": "stop-light-observations",
        "name": "Stop Light Observations",
        "date_updated": "2017-10-14T00:00:00+00:00",
        "tunefind_url": "https://www.tunefind.com/artist/stop-light-observations",
        "tunefind_api_url": "https://[ENDPOINT].api.tunefind.com/api/v2/api/v2/artist/stop-light-observations"
      }
    },
  ]
}

Document History