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!
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:
Alternatively, you can specify the following additional GET parameter:
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
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).
- https://secondhandsongs.com/search/object (generic search)
- pageSize (optional): the number of results per response
- page (optional): the number of the requested page
- search criteria:
- performer (optional)
- date (optional)
- credits (optional)
- object: artist, performance or work
- caption: artist commonName, performance title or work title
The responses consist of a list of entities, as specified in 'SHS Data Types'.
The URLs are the same as for the website, e.g.:
The responses consist of one entity, as specified in 'SHS Data Types'.