Provider metadata blocks (Apple Music, Spotify, Deezer, MusicBrainz)

The return parameter is for comma-separated identifiers of the additional metadata you want to be returned. The identifiers you can send: musicbrainz – MusicBrainz metadata; apple_music, spotify, deezer – Apple Music, Spotify, Deezer data and links respectively. Example: apple_music,spotify.

If there are matches, the result has the data requested in the return parameter in fields corresponding to the identifiers. Each block has the same structure as the provider’s own track object (an array of recordings for MusicBrainz), so you don’t need a second call to the provider. The Apple Music, Spotify, and MusicBrainz blocks contain the same ISRC for the same recording, so you can join the metadata from several providers by ISRC. The fields depend on the provider; see the page for each block.

Identifier	Block	Shape	Contents	Reference (fields and the provider’s full schema)
`apple_music`	Apple Music	object	Apple Music URL, preview, artwork, Apple Music IDs	Apple Music metadata block
`spotify`	Spotify	object	Spotify URL, preview, artwork, Spotify IDs	Spotify metadata block
`deezer`	Deezer	object	Deezer URL, preview, artwork, Deezer IDs	Deezer metadata block
`musicbrainz`	MusicBrainz	array of recordings	MusicBrainz recordings and releases	MusicBrainz metadata block

Note: In the past, the API also accepted napster. Napster metadata is no longer available: the platform ceased operations, and napster was removed from the API. Sending it will add warning #51 to your API responses.

Some metadata is computationally expensive for the API to provide: AudD has to look the track up in another service, and each provider you list makes the request slower. For performance reasons, the default response excludes those blocks. To obtain those blocks, list the providers in return, and list only the ones you will read.

Requesting metadata blocks

You can send all the parameters as GET URL parameters or as POST form data parameters, even though it’s better to send the parameters in the POST body. Send the identifiers in the return parameter, separated by commas:

curl https://api.audd.io/ \
  -F api_token=your-api-token \
  -F url=https://audd.tech/example.mp3 \
  -F return=apple_music,spotify,deezer,musicbrainz

When you make a request with the SDKs, the return parameter is passed as an option to the recognize method. For Python, use the return_metadata option to pass the list of providers. In the other SDKs, the option has the same name in the language’s own case: returnMetadata in Node, for example.

from audd import AudD

audd = AudD("your-api-token")  # dashboard.audd.io
result = audd.recognize(
    "https://audd.tech/example.mp3",
    return_metadata=["apple_music", "spotify", "musicbrainz"],
)

import { AudD } from "@audd/sdk";

const audd = new AudD({ apiToken: "your-api-token" }); // dashboard.audd.io
const result = await audd.recognize("https://audd.tech/example.mp3", {
  returnMetadata: ["apple_music", "spotify", "musicbrainz"],
});

The blocks you asked for are typed properties on the result: result.spotify, result.apple_music, and so on (see below for the cases when a block is missing). Their fields are typed too. Fields that the SDK has no typed property for are included in model_extra (Python) or extras (Node) instead of being omitted. For more information about reading a block, see the page for that block.

Parameter	Default	Description
`return`	none	Comma-separated identifiers of the blocks you want: `apple_music`, `spotify`, `deezer`, `musicbrainz`
`market`	`us`	Country code for the Apple Music and Spotify lookups: the catalog entry and `available_markets` of that country. Deezer and MusicBrainz blocks: the same for every country

If the server has successfully processed the request but the provider has no match for the song, the block can be null or absent, even if you asked for it. Check the block before you read its fields. Every field inside a block is optional and may be omitted or null too.

By default, the enterprise endpoint doesn’t return the provider blocks. On enterprise matches, use song_link (below) to link to the services. If you need the blocks with the enterprise results, contact us: [email protected].

`song_link`

We add URLs of song pages with links to the streaming platforms to the metadata we send with all the results: song_link links to a lis.tn song page like https://lis.tn/NbkVb. It’s there on the standard and the enterprise endpoint, with or without return.

{ "result": { "song_link": "https://lis.tn/NbkVb" } }

The same link gives you the cover art: add ?thumb to it (https://lis.tn/NbkVb?thumb).

If you don’t need a specific service’s own URL, IDs, preview, or artwork in your UI and just want to link to the song or show the cover art, use song_link. You’ll be able to do it without requesting any of the blocks. For more information, see “The lis.tn song link.”

SDK helpers: `streaming_url()`

The SDKs have a streaming_url() method on the result that returns the URL of the recognized song on one streaming service. In the camelCase SDKs, the method is named streamingUrl().

The providers you can pass: spotify, apple_music, deezer (which return the direct URL if you requested the provider’s block, and the lis.tn redirect to the service if you didn’t) and youtube (which has no metadata block, so the method returns the lis.tn redirect). So the method works with or without return. MusicBrainz is a database, not a streaming service, and the method doesn’t accept it.

result = audd.recognize(
    "https://audd.tech/example.mp3",
    return_metadata=["spotify"],
)
result.streaming_url("spotify")      # direct open.spotify.com/track/… (block was requested)
result.streaming_url("apple_music")  # lis.tn redirect (block was not requested)

const result = await audd.recognize("https://audd.tech/example.mp3", {
  returnMetadata: ["spotify"],
});
result.streamingUrl("spotify");      // direct Spotify URL
result.streamingUrl("apple_music");  // lis.tn redirect

Related

Provider metadata blocks (Apple Music, Spotify, Deezer, MusicBrainz)

Requesting metadata blocks

song_link

SDK helpers: streaming_url()

`song_link`

SDK helpers: `streaming_url()`