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
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
- 500 requests per day
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":
When using the API key, more data becomes available, for example all External Recordings, these are song links to:
- Apple Music
- Internet Audio Archive
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.:
- Artist Sam Cooke
- Performance I'm Waiting for the Man
- Work Let's Stick Together
- Release Fifth Dimension
- Label Fury Records [US]
The responses consist of one entity, as specified in 'SHS Data Types'.