Welcome to the Luminate Music API developer documentation!

🔐 Authenticate

The first step to accessing the Luminate Music API is to go through the authentication process. Please review the Authentication documentation for an outline of the steps and requirements.

📊 Get Access to Data

The Luminate Music API provides access to data from 50 different territories via 5 endpoints:

/musical_recordings (ISRC)
/song
/musical_products (Barcode)
/musical_release_groups (Album)
/artists

Retrieve the following types of data from the aforementioned endpoints:

Metadata
Relationships
Discography
External IDs
Consumption Data

The Luminate Music API includes intelligent categorization of consumption data via "breakouts", allowing users to understand the various methods in which the market consumed the specified ID.

{
  "metrics": [
    {
      "name": "Streams",
      "value": [
        {
          "name": "total",
          "value": 19892402
        },
        {
          "name": "commercial_model",
          "value": [
            {
              "name": "ad_supported",
              "value": 3204397
            },
            {
              "name": "premium",
              "value": 16688005
            }
          ]
        },
        {
          "name": "content_type",
          "value": [
            {
              "name": "audio",
              "value": 19194807
            },
            {
              "name": "video",
              "value": 697595
            }
          ]
        },
        {
          "name": "service_type",
          "value": [
            {
              "name": "on_demand",
              "value": 18733631
            },
            {
              "name": "programmed",
              "value": 1158771
            }
          ]
        }
      ]
    }
  ]
}

🎛️ Use Filters to Derive Insights

Our new Data Filters enable the user to analyze the data with precise granularity. All of the breakouts that are returned in the API can be used as query parameters. For example, by appending content_type=audio, you will filter all of the streaming activity by audio-based streams. Multiple filters can be applied to a single request for deeper analysis: content_type=audio&service_type=on_demand.

See the Data Filters documentation for further information on this topic.

{
  "metrics": [
    {
      "name": "Streams",
      "value": [
        {
          "name": "total",
          "value": 18036036
        },
        {
          "name": "commercial_model",
          "value": [
            {
              "name": "ad_supported",
              "value": 1419881
            },
            {
              "name": "premium",
              "value": 16616155
            }
          ]
        },
        {
          "name": "content_type",
          "value": [
            {
              "name": "audio",
              "value": 18036036
            },
            {
              "name": "video",
              "value": 0
            }
          ]
        },
        {
          "name": "service_type",
          "value": [
            {
              "name": "on_demand",
              "value": 18036036
            },
            {
              "name": "programmed",
              "value": 0
            }
          ]
        }
      ]
    }
  ]
}

🔍 Can't Find What You're Looking For? Use Search!

The Search endpoint allows users who do not have identifiers to query the Luminate Music API using lexical search. After specifying an entity_type and query string, the search endpoint will return a list of IDs that match the search criteria. The following entity_types are supported by the /search endpoint:

musical_recording (ISRC)
song
musical_product (Barcode)
musical_release_group (Album)
artist

The from and size fields can be used for pagination. By default, the endpoint will return up to 10 entries, starting from the beginning of the index. The user can request up to 500 results in a single response and one string search can yield a maximum of 10,000 matches.

curl --request POST \
     --url https://api.luminatedata.com/search \
     --header 'Accept: application/vnd.luminate-data.svc-apibff.v1+json' \
     --header 'authorization: AUTHTOKEN123' \
     --header 'content-type: application/json' \
     --header 'x-api-key: APIKEY123 \
     --data '
{
  "query": "luminate",
  "entity_type": "song",
  "from": 0,
  "size": 10
}
'

{
  "results": [
    {
      "id": "SGAF8028E3EAB54A208359218EAE1E2E4D",
      "title": "Luminate Luminate",
      "display_artist_name": "Chilled Jazz Classics"
    },
    {
      "id": "SGFA8426272C924A02A5B3D7A28BA14993",
      "title": "Luminate",
      "display_artist_name": "Lukasz"
    },
    {
      "id": "SGD6F0BB8B76EE419F9852FC8B2D663DB8",
      "title": "Luminate",
      "display_artist_name": "LVL96"
    },
    {
      "id": "SG42DC982D8F7142A0806C58FAE463FF16",
      "title": "Luminate",
      "display_artist_name": "Lighthouse Livada"
    },
    {
      "id": "SG5546086AE432498188B560AD2F3F0A85",
      "title": "Luminate",
      "display_artist_name": "LoeKey"
    },
    {
      "id": "SG3CD9FD9DEECD445FB060AEB707742A2A",
      "title": "Luminate",
      "display_artist_name": "Angelo Reth"
    },
    {
      "id": "SG87BD9750D21E442E8CE2E3C97893CB8C",
      "title": "Luminate",
      "display_artist_name": "Nwnil"
    },
    {
      "id": "SGD253BF813AB94AEA8A19B7F6E1D3F6FE",
      "title": "Luminate",
      "display_artist_name": "Arandas Black"
    },
    {
      "id": "SGD72F34F1B0384EB58D780EB19AEB1B5B",
      "title": "Luminate",
      "display_artist_name": "Madkat"
    },
    {
      "id": "SG2B233D1BEB8145898F41367983352AC8",
      "title": "Luminate",
      "display_artist_name": "Star Gardener"
    }
  ],
  "from": 0,
  "size": 10,
  "total_results": 1499
}

📬 Improve Your Queries with Developer-Friendly Error Messaging

Encountered a 4xx or 5xx error when querying the Luminate Music API? No fear! Our developer-friendly error messages will quickly identify the root cause and guide you to a successful request.

{
    "error": {
        "errors": [
            {
                "error_code": "00017",
                "error_type": "Incompatible Values",
                "message": "start_date must be less than or equal to end_date."
            }
        ],
        "code": 400,
        "message": "Bad Request"
    }
}

🛟 We're here to help!

Please reach out to [email protected] if you have any questions.