Search

Detailed search

The SecondHandSongs API (BETA)

The SecondHandSongs (SHS) API offers two functionalities:

  • Search (artists, performances and works)
  • Retrieve information of SHS objects (artists, performances, releases, ...)

The API is RESTful. The parameters are sent as query-string and the result is return as a JSON object.

The SHS API is still in beta testing!

License

The SHS data is licensed under the Creative Commons license CC BY-NC 3.0. It is free for any non-commercial use and must be attributed to "SecondHandSongs.com".

The data is protected by law in two ways:

  • By copyright: the distinction between works and performances and their relations is not factual, but a creative effort by SHS.
  • By "Sui Generis" right.

How to access the SHS API

The API is accessed through HTTP, by using the URLs of the website. In order to get the API results instead of the normal webpages, the following header must be specified:

Accept: application/json

Alternatively, you can specify the following additional GET parameter:

format=json

When not using an API key, the calls to the API are limited to:

  • 10 requests per minute
  • 100 requests per hour

These limitations are checked with a sliding window.

If you need more throughput, request an API key. Once you have received it, provide the API key as HTTP header "X-API-Key":

X-API-Key: ed0a8c61-4520-4317-9b95-7a260260b4c

SHS Data Types

Responses are made out of SHS Data Types, which are hierarchical. Click on the data types for more information.

An SHS object can have the following attributes:

  • entityName: the specific data type (e.g. 'audio single' when a release is expected)
  • uri: the uri of the REST resource
  • external_uri (optional): links to URI's hosted in other domains (e.g. Discogs, YouTube)

Additional attributes vary according to types and the context (e.g. a performance in a search result will show only performer and title). Some attributes are always displayed (marked in italic on the documentation pages).

API Functionality

Home page

URL:

Content:

Search

URLs:

Parameters:

  • pageSize (optional): the number of results per response
  • page (optional): the number of the requested page
  • search criteria:
    • artist
      • commonName
    • performance
      • title
      • performer (optional)
      • date (optional)
    • work
      • title
      • credits (optional)
    • object: artist, performance or work
      • caption: artist commonName, performance title or work title

Example:

https://secondhandsongs.com/search/performance?title=blackbird&performer=beatles

The responses consist of a list of entities, as specified in 'SHS Data Types'.

Objects

The URLs are the same as for the website, e.g.:

The responses consist of one entity, as specified in 'SHS Data Types'.

Info Centre