For each entity type (Artist, Album, Track, Playlist, etc.), the following data must be provided to make it supported by the search functionality in Linkfire:

• Internal ID - Unique identifier for the entity so it's possible to distinguish between different entities.
• Name - The name of the entity. It could be an artist's name, track title, album title, etc.
• Countries- List of countries where the entity is available. It should be a list of 2-digit ISO codes. It can be part of the API response (feed item) for each entity or a static list for the whole service.
• Destination URL- The URL that the user should be redirected to when clicking on the entity. Instead of the URL, it can be a guide for composing the URL using the available entity metadata (e.g., Internal ID, name slug, and so on).

The following fields are not mandatory but highly recommended as they increase the quality of search results and user experience:

• Aliases - Additional names for entities, such as nicknames, translations, transcriptions, most popular typo errors, etc. Aliases help to find the entity by different names.
• Additional IDs - A list of additional identifiers known for the entity. This includes, but is not limited to, ISRC, UPC, EAN, etc. Additional IDs help find the entity using different identifiers.
• Artwork - URL to the entity's artwork. The image should be at least 320x320 pixels. Linkfire supports multiple artworks per entity in different dimensions and can be used for various purposes.

In addition to the above fields, Linkfire needs information on how to map the destination URL to the entity. In most cases, it's possible to parse the destination URL and extract the entity ID from it. But in some cases, a guide on how to treat the URL to find the entity is required.

While Linkfire supports different authentication methods, the preferred method is to use OAuth2 authentication with refresh tokens. This allows Linkfire to authenticate once and reuse the token across multiple services without the need to re-authenticate each time, reducing the number of requests to the integration authentication endpoint.

Linkfire respects rate limits and can adjust the number of requests to the integration API based on the rate limit provided by the integration. It's recommended that the rate limit information be provided in the API documentation or the response headers.

Linkfire supports caching of the API responses to reduce the number of requests to the integration API. It's recommended that caching information be provided in the API documentation or the response headers.

Linkfire supports the following search capabilities:

• Text search - Linkfire tries to find the entity using the text query generated from available entity metadata. For example, Linkfire can use artist names, release titles with or without editions, release types, and so on for music releases.
• ID search - Linkfire can query entities by IDs if it's supported by integration. Thus, it's possible to query multiple entities by a single request. This type of search includes the following:
  • Search by UPC - Linkfire can query the release by UPC.
  • Search by ISRC - Linkfire can query the track by ISRC.
  • Search by entity ID - Linkfire can query the entity using the internal ID provided by the integration.
• URL Lookup - As mentioned above, Linkfire can parse the destination URL and extract the entity ID from it. However, in some cases, the integration can provide a way to find the entity by the destination URL.

Linkfire supports different data feed formats, such as JSON, XML, CSV, etc. The preferred format is any machine-friendly format such as JSON or XML. The feed should include all the required fields for each entity type, as described above.

There are no strict requirements for the data feed update frequency, as covering all cases for all catalogues is impossible. However, it's recommended that the feed be updated at least once a month to provide Linkfire with the most up-to-date information.

Linkfire supports incremental updates from the data feed integration. The incremental update should include only changes for the period since the last full or incremental update.

While it's up to the integration how to organize the data feed, providing the feed in a structured way is recommended to make it easier to parse and process. One way of doing this could be the following:

|-- <YYYY-MM-DD>
|   |-- <entity_type>.<full|incremental>.<json|xml|csv|...>
|-- ...

For example:

|-- 2021-01-01
|   |-- artist.full.json
|   |-- release.full.json
|-- 2021-01-02
|   |-- track.incremental.json
|-- 2021-02-01
|   |-- artist.full.json
|   |-- release.full.json
|   |-- track.full.json
|-- ...

Linkfire supports different data feed delivery methods. The preferred way is to use the following:

• Cross Account S3 bucket replication to Linkfire S3 Ingress
  • HOWTO: Cross Account S3 bucket replication to Linkfire S3 Ingress
• 3rd party PUSH through script/AWS API to Linkfire S3 Ingress
• 3rd Party SFTP to Linkfire
• Linkfire PULLs from 3rd Party to S3

The following sections specify the additional fields supported by Linkfire for each entity type in the music industry. Integration may support only some entity types and only some things.

• Discography - A list of artist albums and track names. Preferably, releases should include UPCs, and tracks should include ISRCs. Discography helps provide more consistent search results across integrations for artists with the same name.
• Genres - List of genres the artist is associated with, preferably as an array of string values. But it can be a single comma-separated string or a list of genre IDs from the DSP database. In general, genres help better attribute created links.
• Labels - List of music labels that the artist is associated with. Labels help to provide more consistent search results across integrations for artists with the same name.
• Popularity - Popularity indication for the artist. It can be represented as several followers, monthly listeners, or any other popularity metric. Popularity helps to sort search results by relevance and can be a tiebreaker for artists with the same name.

In the music industry context, a release can be an album, single, EP, or any other music release. The following fields are recommended for each release:

• Artists - List of artists associated with the release. Preferably, include the artist's name and ID for the DSP, making it possible to find more relevant results using text search.
• Duration - The total length of the release in seconds or any other well-known format.
• Genres - List of genres associated with the release. Preferably as an array of string values. But it can be a single comma-separated string or a list of genre IDs from the DSP database. In general, genres help better attribute created links.
• Release Date - for music releases, the Release Date can be one of the following or both:
  • Original Release Date - The date the release was published first, not necessarily when it was added to the service.
  • Street Date - The date the release is available for purchase or streaming. It can be the same as the original release date.
• Labels - List of music labels associated with the release.
• Name - For music releases, the name can include the release title, the edition, version, or any other information that is not useful for search but can be used for display purposes. Thus, the release name can be separated into the following fields:
  • Name - The release title with all suffixes as-is.
  • CleanName - The release title without any additional information. This version of the name is much more useful in search.
  • EditionName - The edition, version, or any other additional information which is not helpful for search but can be used for display purposes.
• Sample - Sample URL for the release. It can be a preview of the release, a snippet of the track, or any other sample that helps to promote the release.
• Type - The type of the release. It can be an album, single, EP, or any other release type. Type helps to provide more consistent search results across integrations for releases with the same name.
• UPC - One of the most popular and globally available identifiers for music releases. UPC helps to find the release by its identifier, even if it has different names across integrations.

The track fields are similar to the release fields but more focused on the track itself. A field unavailable for tracks can be taken from the parent release.

• Artists - List of artists associated with the track. Preferably, include the artist's name and ID for the DSP; this makes it possible to find more relevant results using text search. It's expected that the list of artists can differ from the list of artists for the release.
• Duration - The length of the track in seconds or any other well-known format.
• Name - For music tracks, the name can include the track title, release title, edition, version, or any other information that is not useful for search but can be used for display purposes. Thus, the track name can be separated into the following fields:
  • Name - The track title with all suffixes as-is.
  • CleanName - The track title without any additional information. This version of the name is much more useful in search.
  • EditionName - The edition, version, or any other additional information which is not helpful for search but can be used for display purposes.
• Release - The release that the track is associated with. The release title and ID for the DSP should be included; this makes it possible to find more relevant results using text search.
• Sample - The Sample URL for the track. Usually, it's a 30-second preview of the track.
• ISRC - One of the most popular and globally available identifiers for music tracks. ISRC helps to find the track by its identifier, even if it has different names across integrations.

The following table summarizes the general requirements for each entity type:

See the Music Metadata Requirements section for more information.

See the Music Metadata Requirements section for more information.

See the Music Metadata Requirements section for more information.

TBD