MusicGraph API Documentation


Welcome to the MusicGraph API documentation!

You can use the MusicGraph API to search through more than 7 billion music facts and connections. Data is stored in a graph database, which you can query using familiar REST HTTP calls. This document specifies the set of HTTP methods exposed by the MusicGraph API.

All URLs pertaining to the MusicGraph API share a common base path:

General Guidelines

We need to protect users, content providers, our software and service while at the same time enable you to create applications. We therefore require you to comply with the following terms.

- Before you start developing anything using the MusicGraph API, you need to read and abide by the full Terms Of Service.

- Please use an identifiable User-Agent header on all requests. This helps our logging and reduces the risk of you getting banned.

- Use common sense when deciding how many calls to make. For example, if you're making a web application, try not to hit the API on page load. Your account may be suspended if your application is continuously making several calls per second.

- Don't use the API or feeds in connection with anything that promotes or takes part in any products, services, or materials that we would consider malicious, hateful, or illegal.

- You may not sell, lease, share, transfer, or sub-license the API or feeds or access to the API to any other party than the API key holder. You can cache our data to lighten bandwidth and improve latency.


All requests made to the MusicGraph API must be signed with an API key. The API key used in this document is for demonstration purposes only. It should not be used for any other application as it is rate limited and restricted by IP. You can sign up for a free account here.


Use UTF-8 encoding when sending arguments to API methods.

Response Codes

-1 - Unknown Error

0 - Success

1 - Missing/ Invalid API Key

2 - This API key is not allowed to call this method

3 - Rate Limit Exceeded

4 - Not Supported

5 - Invalid Search Operation

6 - Invalid Edge Name

7 - Invalid MusicGraph ID

8 - Invalid Type

HTTP Response Codes

The HTTP Status response status code can be used to determine the status of an API request:

200 - Success

304 - Not Modified

400 - Bad Request - the request is not valid

403 - Forbidden - you are not authorized to access that resource

404 - Incorrect path; Not Found - The requested resource could not be found

429 - Too Many Requests - You have exceeded the rate limit associated with your API key

5XX - Server Error

Sending Requests

The API is implemented directly over HTTP. In general, HTTP GET methods are used for read-only operations while HTTP POST are reserved for requests that potentially modify state on the server.

Most queries support cursor-based pagination. The offset parameter offsets the start of each page by the number specified. The limit parameter limits the number of objects to be returned. The maximum allowable count is 100.

Standard Parameters

These parameters are valid for all methods in the API.

api_key - the developer api key

Optional Parameters

Name Description
fields Limit the set of returned properties; comma-separated
limit Limit the number of results; max is 100, default is 15
offset Paginate the results set

The MusicGraph API is strongly typed. In addition to having a type, every object has a unique id and any number of additional fields and connections to other objects associated with it. Developers can limit the set of returned properties using the fields query parameter. It accepts a comma-separated list of values.

By default, all fields are returned when you make an API request. You can select what fields you want returned with the fields parameter.

GET /api/v2/{node}/{id}?fields=id,name

Making Nested Requests

The field expansion feature of the MusicGraph API, allows you to effectively nest multiple graph queries into a single call.

Here is the general format that field expansion takes:


{first-level} in this case would be one or more (comma-separated) fields or edges from the parent node. {second-level} would be one or more (comma-separated) fields or edges from the first-level node.

You can also use a .limit(n) argument on each field or edge to restrict how many objects you want to get.

Note: Nesting is available on direct edges of the parent node.

Here's an example query that will retrieve the ID and title of up to ten albums by Adele.

GET /api/v2/artist/ee2564c7-a6b5-11e0-b446-00251188dd67?api_key=c8303e90962e3a5ebd5a1f260a69b138&fields=id,name,albums.limit(10).fields(id,title)

Here's an example query that will retrieve the ID and title of up to ten tracks by Adele.

GET /api/v2/artist/ee2564c7-a6b5-11e0-b446-00251188dd67?api_key=c8303e90962e3a5ebd5a1f260a69b138&fields=id,name,tracks.limit(10).fields(id,title)

If you want to pull in Adele's albums and tracks, you can just append to the url.

GET /api/v2/artist/ee2564c7-a6b5-11e0-b446-00251188dd67?api_key=c8303e90962e3a5ebd5a1f260a69b138&fields=id,name,albums.limit(10).fields(id,title),tracks.limit(5).fields(id,title)

The default limit on the number of returned objects is 15. You can override the default limit with the limit query parameter, which accepts any number between 1 and 100. Similarly, you can use the offset query parameter to perform pagination on the results set.

GET /api/v2/artists/search?similar_to={value}&limit=20&offset=1

Release History

12/15/2014: Released multi-seeding of playlists. Seeds include artist, track, genres and decades

12/10/2014: Released genre and decade filters for artist, album, and track suggest

04/21/2014: v2 Released

v1: Initial Release