Search integration requirements - GetLinkfire/Integrations GitHub Wiki
All
Internal Id: Internal ID used for de-duplication and generating urls if possible
Web url: Required, If we can't compose the url from the Internal ID
Mobile url: mobile url only required if different from the Web url. meaning, if they have an app that requires a specific schema.
Artist page:
If the external service has an artist page, the following data is necessary for each artist. The artist name should be searchable:
| Mandatory | Highly recommended | Optional | If possible | |
|---|---|---|---|---|
| Artist name | x | |||
| Internal Id | x | |||
| Mobile url (if app available and can’t be composed by id) | x | |||
| Genre as an array of string values | x | |||
| Artist Popularity indication | x | |||
| Artist image url | x | |||
| International Artist name | x | |||
| Mobile url | x |
Album page:
If the external service has the option to link to albums, the following data should be provided for each album. Combination of album and artist name should be searchable:
| Mandatory | Highly recommended | Optional | If possible | |
|---|---|---|---|---|
| Album name | x | |||
| Internal Id | x | |||
| Artist name | x | |||
| Web url | x | |||
| Label | x | |||
| Release date | x | |||
| List of available countries (if geographically limited) 2 digit iso code | x | |||
| Search top albums per artist id | x | |||
| Release country | x | |||
| Genre as an array of string values | x | |||
| Upc code | x | |||
| Album Popularity indication | x | |||
| Number of tracks | x | |||
| Length of album (total number of seconds for all tracks) | x | |||
| Samples (optional): Sample Track URl | x | |||
| Artwork url (if possible min. 320x320) | x | |||
| Mobile url | x |
Track page
If the external service has the option of linking directly to tracks the following data should be provided for each track. Combination of artist name and track name should be searchable:
| Mandatory | Highly recommended | Optional | If possible | |
|---|---|---|---|---|
| Track name | x | |||
| Internal Id | x | |||
| Artist name | x | |||
| Label | x | |||
| Web url | x | |||
| List of available countries (if geographically limited) 2 digit iso code | x | |||
| Search top tracks per artist id | x | |||
| Album name | x | |||
| ISRC code | x | |||
| UPC code | x | |||
| Genre as an array of string values | x | |||
| Track Popularity indication | x | |||
| Tracklength | x | |||
| Sample url | x | |||
| Artwork url (if possible min. 320x320) | x | |||
| Mobile url | x |
Playlist page
If the external service has the option of linking directly to playlists the following data should be provided for each playlist. Combination of playlist name, artist name and track name should be searchable:
| Mandatory | Highly recommended | Optional | If possible | |
|---|---|---|---|---|
| Playlist name | x | |||
| Internal Id | x | |||
| Playlist Source: Source URL | x | |||
| Number of tracks | x | |||
| Tracklist: List of Artist & Track names | x | |||
| Creator | x | |||
| Artwork: Same as artwork for Albums/Tracks | x | |||
| Creation Date | x |
Recommended endpoint structure
| Description | Mandatory | Highly recommended | Optional | Mandatory Params | Optional Params |
|---|---|---|---|---|---|
| SearchTrack | |||||
| {baseUrl}/search/tracks?track={trackTitle}&album={albumTitle?}&artist={artistName?} | x | track | album, artist | ||
| {baseUrl}/search/tracks?id={id} | x | ||||
| {baseUrl}/search/tracks?isrc={isrc} | x | ||||
| {baseUrl}/search/tracks?ids={ids} | x | ||||
| {baseUrl}/search/tracks?isrc={isrcs} | x | ||||
| {baseUrl}/search/tracks?album={albumTitle}&artist={artistName?} | x | track | album, artist | ||
| {baseUrl}/search/tracks?artist={artistName} | x | ||||
| {baseUrl}/search/tracks?albumId={albumId} | x | ||||
| {baseUrl}/search/tracks?artistId={artistId} | x | ||||
| SearchAlbum | |||||
| {baseUrl}/search/albums?album={albumTitle}&artist={artistName?} | x | album | artist | ||
| {baseUrl}/search/albums?id={id} | x | ||||
| {baseUrl}/search/albums?upc={upc} | x | ||||
| {baseUrl}/search/albums?ids={ids} | x | ||||
| {baseUrl}/search/albums?upc={upcs} | x | ||||
| {baseUrl}/search/albums?artistid={artistId} | x | ||||
| {baseUrl}/search/albums?artist={artistName} | x | ||||
| SearchArtist | |||||
| {baseUrl}/search/artists?artist={artistName} | x | ||||
| {baseUrl}/search/artists?id={id} | x | ||||
| {baseUrl}/search/artists?ids={ids} | x |
Notes to Recommended endpoint structure:
- It would be nice to support offset & limit params for search endpoints.
- It is also fine to use single /search?types=tracks,albums,artists endpoint by adding types parameter to the request:
- {baseUrl}/search?types=tracks&track={trackTitle}&....
- {baseUrl}/search?types=tracks,albums,artists&track={trackTitle}&....
Data feeds If a data dump is used, the file should be regenerated at least every 24 hours. Linkfire will then download the file and search it locally.