RecoupGet a Free AuditFree Audit

API REFERENCE

Songs by ISRC

On this page
GET/api/apple/songs

Look up recordings in the Apple Music catalog by ISRC. Accepts up to 25 comma-separated ISRCs per request and returns one row per requested ISRC, so a recording that Apple does not carry comes back explicitly as found: false rather than being omitted. Complements GET /api/spotify/search, which reaches ISRCs only through a fuzzy isrc: search query; Apple matches the identifier exactly and additionally returns release-level rights metadata (upc, record_label, copyright) that Spotify does not expose.

Authentication

x-api-key in header

bearerAuth bearer

Request

cURL
curl --request GET \
  --url 'https://api.recoupable.dev/api/apple/songs?isrc=DEH742611917%2CTCAEC1931080' \
  --header 'x-api-key: YOUR_API_KEY'

Replace the YOUR_ placeholders with your values. Required query parameters are included; optional parameters are listed below.

Parameters

Query parameters

isrcstringrequired

One or more ISRCs, comma-separated. Case-insensitive; each must match the 12-character ISRC format (two-letter country code, three-character registrant code, two-digit year, five-digit designation). Maximum 25 per request.

storefrontstring

Apple Music storefront to search, as a two-letter country code. Availability is territory-specific, so a recording present in one storefront may be absent from another.

Default: "us"

Responses

200Lookup completed. One entry per requested ISRC, in the order requested.

application/json

statusstring · enum

Status of the request

Values: "success"

storefrontstring

The storefront the lookup ran against

resultsarray<AppleIsrcResult>

One entry per requested ISRC, in the order requested

Item properties for results
isrcstring

The requested ISRC, uppercased

foundboolean

Whether Apple Music carries at least one recording with this ISRC in the requested storefront

songsarray<AppleSong>

Every recording Apple returns for this ISRC. Usually one, but the same recording can appear on several releases (compilations, anniversary editions), each with its own song id.

Item properties for songs
idstring

Apple Music catalog song id

isrcstring
namestring
artist_namestring

Display credit as Apple renders it, which may combine several artists

composer_namestringnullable
album_namestring
release_datestringnullable

format: date

duration_msinteger
track_numberintegernullable
disc_numberintegernullable
genre_namesarray<string>
Item properties for genre_names

string

has_lyricsboolean
is_apple_digital_masterboolean
audio_variantsarray<string>

Delivery formats available, for example lossless, lossy-stereo, dolby-atmos

Item properties for audio_variants

string

urlstring

Public Apple Music page for the recording

artwork_urlstringnullable

Artwork template URL. Substitute {w} and {h} with the pixel dimensions you want.

preview_urlstringnullable

30-second AAC preview

albumobjectnullable

The release this recording appears on. Carries the rights metadata Apple exposes and Spotify does not.

Properties for album
idstring
namestring
upcstringnullable
record_labelstringnullable
copyrightstringnullable

The phonographic copyright line

release_datestringnullable

format: date

track_countintegernullable
is_singleboolean
is_compilationboolean
is_completeboolean

Whether every track on the release is available in this storefront

urlstring
400Bad request - isrc missing, malformed, or over the 25-ISRC limit, or an unknown storefront

application/json

statusstring · enum

Status of the request

Values: "error"

errorstring

Human-readable error message

400 example
{
  "status": "error",
  "error": "isrc must be a valid ISRC: NOTANISRC"
}

401Unauthorized - missing or invalid credentials

application/json

statusstring · enum

Status of the request

Values: "error"

errorstring

Human-readable error message

401 example
{
  "status": "error",
  "error": "Exactly one of x-api-key or Authorization must be provided"
}

500Internal server error, including a failure to reach the Apple Music API

application/json

statusstring · enum

Status of the request

Values: "error"

errorstring

Human-readable error message

500 example
{
  "status": "error",
  "error": "Failed to reach the Apple Music API"
}

Full specification

Download the OpenAPI file for complete schemas, constraints, and examples.

Download social.json
View operation source
json
{
  "description": "Look up recordings in the Apple Music catalog by ISRC. Accepts up to 25 comma-separated ISRCs per request and returns one row per **requested** ISRC, so a recording that Apple does not carry comes back explicitly as `found: false` rather than being omitted. Complements `GET /api/spotify/search`, which reaches ISRCs only through a fuzzy `isrc:` search query; Apple matches the identifier exactly and additionally returns release-level rights metadata (`upc`, `record_label`, `copyright`) that Spotify does not expose.",
  "security": [
    {
      "apiKeyAuth": []
    },
    {
      "bearerAuth": []
    }
  ],
  "parameters": [
    {
      "name": "isrc",
      "in": "query",
      "description": "One or more ISRCs, comma-separated. Case-insensitive; each must match the 12-character ISRC format (two-letter country code, three-character registrant code, two-digit year, five-digit designation). Maximum 25 per request.",
      "required": true,
      "schema": {
        "type": "string",
        "example": "DEH742611917,TCAEC1931080"
      }
    },
    {
      "name": "storefront",
      "in": "query",
      "description": "Apple Music storefront to search, as a two-letter country code. Availability is territory-specific, so a recording present in one storefront may be absent from another.",
      "required": false,
      "schema": {
        "type": "string",
        "default": "us",
        "example": "gb"
      }
    }
  ],
  "responses": {
    "200": {
      "description": "Lookup completed. One entry per requested ISRC, in the order requested.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/AppleSongsResponse"
          }
        }
      }
    },
    "400": {
      "description": "Bad request - `isrc` missing, malformed, or over the 25-ISRC limit, or an unknown `storefront`",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/AppleErrorResponse"
          },
          "example": {
            "status": "error",
            "error": "isrc must be a valid ISRC: NOTANISRC"
          }
        }
      }
    },
    "401": {
      "description": "Unauthorized - missing or invalid credentials",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/AppleErrorResponse"
          },
          "example": {
            "status": "error",
            "error": "Exactly one of x-api-key or Authorization must be provided"
          }
        }
      }
    },
    "500": {
      "description": "Internal server error, including a failure to reach the Apple Music API",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/AppleErrorResponse"
          },
          "example": {
            "status": "error",
            "error": "Failed to reach the Apple Music API"
          }
        }
      }
    }
  }
}