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
The calls to the API are limited to:
- 100 requests per minute
- 1000 requests per hour These limitations are checked with a sliding window.
If you need more throughput, please contact us!
SHS Data Types
Responses are made out of SHS Data Types, which are hierarchical. Click on the data types for more information.
- shsobject
- artist
- performance
- recording
- work
- song
- poem
- film
- ...
- release
- audio single
- audio album
- video
- ..
- label
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:
- spotlight
- original: performance
- cover: performance
Search
URLs:
- https://secondhandsongs.com/search/artist
- https://secondhandsongs.com/search/performance
- https://secondhandsongs.com/search/work
- https://secondhandsongs.com/search/object (generic search)
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
- artist
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.:
- https://secondhandsongs.com/artist/123
- https://secondhandsongs.com/performance/123
- https://secondhandsongs.com/work/123
- https://secondhandsongs.com/release/123
- https://secondhandsongs.com/label/123
The responses consist of one entity, as specified in 'SHS Data Types'.