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
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
- 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":
X-API-Key: ed0a8c61-4520-4317-9b95-7a260260b4c
When using the API key, more data becomes available, for example all External Recordings, these are song links to:
- Youtube
- Spotify
- 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.
- 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.:
- 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'.