Luminate API Endpoint Parameters

Luminate API Endpoint Parameters

The new API has a host of new filters and endpoints for your use. Below will be a short guide to the values you can enter for specific filters and which endpoints they work for!


musical_recordings/{id} -

  1.       single ISRC level data, referred to as musical_recordings endpoint

  2.       Parameters-

    1. Required-

      1. ID - 

        1. Values-
          1. Luminate ID
          2. ISRC

    2. Optional-

      1. ID_type - 

        1. Values- 
          1. Luminate ID
          2. ISRC
        2. Defaults to Luminate ID

      2. start_date -

        1. Values-
          1. ISO 8601 standard i.e (YYYY-MM-DD)
        2. Defaults to 7 days prior to current date or 7 days prior to the end_date (if entered)

      3. end_date- 

        1. Values-
          1. ISO 8601 standard i.e (YYYY-MM-DD)
        2. Defaults to current date or 7 days after the start_date (if entered)

      4. chart_week

        1. Values-
          1. ISO 8601 standard i.e (yyyy-Www) 2024-W01
        2. 7 day period Friday - Thursday

      5. location - 

        1. Values-
          1. ISO 3166-1 alpha-2 standard
          2. Countries - AR, AT, AU, BE, BO, BR, CH, CL, CO, CZ, DE, DK, EC, ES, FI, FR, GB, GR, HK, HR, HU, ID, IE, IN, IS, IT, JP, KR, LU, MX, MY, NL, NO, NZ, PE, PH, PL, RO, SE, SG, SK, TH, TR, TW, VN, ZA, AA, US, CA
          3. Find a country list here

      6. metadata_level-

        1. Values -
          1. max
          2. min
        2. Defaults to min

      7. external_ids-

        1. Values -
          1. true
          2. false
        2. Defaults to false

      8. relationships -

        1. Values - 
          1. none
          2. all
          3. song
          4. musical_product
          5. musical_release_group
        2. Defaults to none

      9. metrics -

        1. Values -
          1. none
          2. all
          3. streams
          4. song_sales
        2. Defaults to all
        3. Note: if choosing none you will exclude all metadata and only return the metadata
        4. Note: if you would like multiple values you can enter those via commas, ie streams, song_sale

      10. breakouts - 

        1. Values -
          1. none
          2. all
          3. commercial_model
          4. content_type
          5. service_type
        2. Defaults to all
        3. Note: only available for streaming data
        4. Note: if you would like multiple values you can enter those via commas, ie commercial_model, content_type

      11. aggregate_interval -

        1. Values -
          1. total
          2. day
          3. week
          4. chart_week
        2. Defaults to total

      12. commercial_model -

        1. Values -
          1. ad_supported
          2. premium
          3. none
        2. Defaults to none
        3. Note: this will not change the sales data

      13. service_type -

        1. Values- 
          1. on_demand
          2. programmed
          3. none
        2. Defaults to none

      14. content_type -

        1. Values - 
          1. audio
          2. video
          3. none
        2. Defaults to none

songs/{id} -

  1.       song level data, referred to as songs endpoint

  2.       Parameters-

    1. Required-

      1. ID - 

        1. Values-
          1. Luminate ID
          2. ISRC

    2. Optional-

      1. ID_type - 

        1. Values- 
          1. Luminate ID
          2. ISRC
        2. Defaults to Luminate ID

      2. start_date -

        1. Values-
          1. ISO 8601 standard i.e (YYYY-MM-DD)
        2. Defaults to 7 days prior to current date or 7 days prior to the end_date (if entered)

      3. end_date- 

        1. Values-
          1. ISO 8601 standard i.e (YYYY-MM-DD)
        2. Defaults to current date or 7 days after the start_date (if entered)

      4. chart_week

        1. Values-
          1. ISO 8601 standard i.e (yyyy-Www) 2024-W01
        2. 7 day period Friday - Thursday

      5. location - 

        1. Values-
          1. ISO 3166-1 alpha-2 standard
          2. Countries - AR, AT, AU, BE, BO, BR, CH, CL, CO, CZ, DE, DK, EC, ES, FI, FR, GB, GR, HK, HR, HU, ID, IE, IN, IS, IT, JP, KR, LU, MX, MY, NL, NO, NZ, PE, PH, PL, RO, SE, SG, SK, TH, TR, TW, VN, ZA, AA, US, CA
          3. Find a country list here

      6. metadata_level-

        1. Values -
          1. max
          2. min
        2. Defaults to min

      7. external_ids-

        1. Values -
          1. true
          2. false
        2. Defaults to false

      8. relationships -

        1. Values - 
          1. none
          2. all
          3. song
          4. musical_product
          5. musical_release_group
        2. Defaults to none

      9. metrics -

        1. Values -
          1. none
          2. all
          3. streams
          4. song_sales
        2. Defaults to all
        3. Note: if choosing none you will exclude all metadata and only return the metadata
        4. Note: if you would like multiple values you can enter those via commas, ie streams, song_sale

      10. breakouts - 

        1. Values -
          1. none
          2. all
          3. commercial_model
          4. content_type
          5. service_type
        2. Defaults to all
        3. Note: only available for streaming data
        4. Note: if you would like multiple values you can enter those via commas, ie commercial_model, content_type

      11. aggregate_interval -

        1. Values -
          1. total
          2. day
          3. week
          4. chart_week
        2. Defaults to total

      12. commercial_model -

        1. Values -
          1. ad_supported
          2. premium
          3. none
        2. Defaults to none
        3. Note: this will not change the sales data

      13. service_type -

        1. Values- 
          1. on_demand
          2. programmed
          3. none
        2. Defaults to none

      14. content_type -

        1. Values - 
          1. audio
          2. video
          3. none
        2. Defaults to none

artists/{id} -

  1.       artist level data, referred to as artists endpoint

  2.  Parameters-

    1. Required-

      1. ID - 

        1. Values-
          1. Luminate ID
          2. ISNI

    2. Optional-

      1. ID_type - 

        1. Values- 
          1. Luminate ID
          2. ISNI
        2. Defaults to Luminate ID

      2. start_date -

        1. Values-
          1. ISO 8601 standard i.e (YYYY-MM-DD)
        2. Defaults to 7 days prior to current date or 7 days prior to the end_date (if entered)

      3. end_date- 

        1. Values-
          1. ISO 8601 standard i.e (YYYY-MM-DD)
        2. Defaults to current date or 7 days after the start_date (if entered)

      4. chart_week

        1. Values-
          1. ISO 8601 standard i.e (yyyy-Www) 2024-W01
        2. 7 day period Friday - Thursday

      5. location - 

        1. Values-
          1. ISO 3166-1 alpha-2 standard
          2. Countries - AR, AT, AU, BE, BO, BR, CH, CL, CO, CZ, DE, DK, EC, ES, FI, FR, GB, GR, HK, HR, HU, ID, IE, IN, IS, IT, JP, KR, LU, MX, MY, NL, NO, NZ, PE, PH, PL, RO, SE, SG, SK, TH, TR, TW, VN, ZA, AA, US, CA
          3. Find a country list here

      6. metadata_level-

        1. Values -
          1. max
          2. min
        2. Defaults to min

      7. external_ids-

        1. Values -
          1. true
          2. false
        2. Defaults to false

      8. relationships -

        1. Values - 
          1. none
          2. artist
        2. Defaults to none

      9. metrics -

        1. Values -
          1. none
          2. all
          3. streams
          4. sales
        2. Defaults to all
        3. Note: if choosing none you will exclude all metadata and only return the metadata
        4. Note: if you would like multiple values you can enter those via commas, ie streams, song_sale

      10. breakouts - 

        1. Values -
          1. none
          2. all
          3. commercial_model
          4. content_type
          5. service_type
          6. format
        2. Defaults to all
        3. Note: only available for streaming data
        4. Note: if you would like multiple values you can enter those via commas, ie commercial_model, content_type

      11. aggregate_interval -

        1. Values -
          1. total
          2. day
          3. week
          4. chart_week
        2. Defaults to total

      12. discography -

        1. Values -
          1. none
          2. musical_release_group
          3. song
        2. Defaults to none

      13. sales_type -

        1. Values -
          1. song_sales
          2. product_sales
          3. all
          4. none
        2. Defaults to all

      14. commercial_model -

        1. Values -
          1. ad_supported
          2. premium
          3. none
        2. Defaults to none

      15. service_type -

        1. Values- 
          1. on_demand
          2. programmed
          3. none
        2. Defaults to none

      16. content_type -

        1. Values - 
          1. audio
          2. video
          3. none
        2. Defaults to none

      17. format -

        1. Values -
          1. digital
          2. physical
          3. none
        2. Defaults to none

musical_release_group/{id} -

  1.       single ICPN or UPC level data, referred to as musical_release_groups endpoint

  2.  Parameters-

    1. Required-

      1. ID - 

        1. Values-
          1. Luminate ID
          2. ICPN
          3. GRID

    2. Optional-

      1. ID_type - 

        1. Values- 
          1. Luminate ID
          2. ICPN
          3. GRID
        2. Defaults to Luminate ID

      2. start_date -

        1. Values-
          1. ISO 8601 standard i.e (YYYY-MM-DD)
        2. Defaults to 7 days prior to current date or 7 days prior to the end_date (if entered)

      3. end_date- 

        1. Values-
          1. ISO 8601 standard i.e (YYYY-MM-DD)
        2. Defaults to current date or 7 days after the start_date (if entered)

      4. chart_week

        1. Values-
          1. ISO 8601 standard i.e (yyyy-Www) 2024-W01
        2. 7 day period Friday - Thursday

      5. location - 

        1. Values-
          1. ISO 3166-1 alpha-2 standard
          2. Countries - AR, AT, AU, BE, BO, BR, CH, CL, CO, CZ, DE, DK, EC, ES, FI, FR, GB, GR, HK, HR, HU, ID, IE, IN, IS, IT, JP, KR, LU, MX, MY, NL, NO, NZ, PE, PH, PL, RO, SE, SG, SK, TH, TR, TW, VN, ZA, AA, US, CA
          3. Find a country list here

      6. metadata_level-

        1. Values -
          1. max
          2. min
        2. Defaults to min

      7. external_ids-

        1. Values -
          1. true
          2. false
        2. Defaults to false

      8. relationships -

        1. Values - 
          1. none
          2. song
          3. musical_release_group
          4. musical_product
          5. musical_recording
          6. all
        2. Defaults to none

      9. metrics -

        1. Values -
          1. none
          2. all
          3. streams
          4. sales
        2. Defaults to all
        3. Note: if choosing none you will exclude all metadata and only return the metadata
        4. Note: if you would like multiple values you can enter those via commas, ie streams, song_sale

      10. breakouts - 

        1. Values -
          1. none
          2. all
          3. commercial_model
          4. content_type
          5. service_type
          6. format
        2. Defaults to all
        3. Note: only available for streaming data
        4. Note: if you would like multiple values you can enter those via commas, ie commercial_model, content_type

      11. aggregate_interval -

        1. Values -
          1. total
          2. day
          3. week
          4. chart_week
        2. Defaults to total

      12. sales_type -

        1. Values -
          1. song_sales
          2. product_sales
          3. all
          4. none
        2. Defaults to all

      13. commercial_model -

        1. Values -
          1. ad_supported
          2. premium
          3. none
        2. Defaults to none

      14. service_type -

        1. Values- 
          1. on_demand
          2. programmed
          3. none
        2. Defaults to none

      15. content_type -

        1. Values - 
          1. audio
          2. video
          3. none
        2. Defaults to none

      16. format -

        1. Values -
          1. digital
          2. physical
          3. none
        2. Defaults to none

musical_products/{id} -

  1.       album level data, referred to as musical_products endpoint

  2. Parameters-

    1. Required-

      1. ID - 

        1. Values-
          1. Luminate ID
          2. ICPN
          3. GRID

    2. Optional-

      1. ID_type - 

        1. Values- 
          1. Luminate ID
          2. ICPN
          3. GRID
        2. Defaults to Luminate ID

      2. start_date -

        1. Values-
          1. ISO 8601 standard i.e (YYYY-MM-DD)
        2. Defaults to 7 days prior to current date or 7 days prior to the end_date (if entered)

      3. end_date- 

        1. Values-
          1. ISO 8601 standard i.e (YYYY-MM-DD)
        2. Defaults to current date or 7 days after the start_date (if entered)

      4. chart_week

        1. Values-
          1. ISO 8601 standard i.e (yyyy-Www) 2024-W01
        2. 7 day period Friday - Thursday

      5. location - 

        1. Values-
          1. ISO 3166-1 alpha-2 standard
          2. Countries - AR, AT, AU, BE, BO, BR, CH, CL, CO, CZ, DE, DK, EC, ES, FI, FR, GB, GR, HK, HR, HU, ID, IE, IN, IS, IT, JP, KR, LU, MX, MY, NL, NO, NZ, PE, PH, PL, RO, SE, SG, SK, TH, TR, TW, VN, ZA, AA, US, CA
          3. Find a country list here

      6. metadata_level-

        1. Values -
          1. max
          2. min
        2. Defaults to min

      7. external_ids-

        1. Values -
          1. true
          2. false
        2. Defaults to false

      8. relationships -

        1. Values - 
          1. none
          2. song
          3. musical_release_group
          4. musical_product
          5. musical_recording
          6. all
        2. Defaults to none

      9. metrics -

        1. Values -
          1. none
          2. all
          3. streams
          4. sales
        2. Defaults to all
        3. Note: if choosing none you will exclude all metadata and only return the metadata
        4. Note: if you would like multiple values you can enter those via commas, ie streams, song_sale

      10. breakouts - 

        1. Values -
          1. none
          2. all
          3. commercial_model
          4. content_type
          5. service_type
          6. format
        2. Defaults to all
        3. Note: only available for streaming data
        4. Note: if you would like multiple values you can enter those via commas, ie commercial_model, content_type

      11. aggregate_interval -

        1. Values -
          1. total
          2. day
          3. week
          4. chart_week
        2. Defaults to total

      12. sales_type -

        1. Values -
          1. song_sales
          2. product_sales
          3. all
          4. none
        2. Defaults to all

      13. commercial_model -

        1. Values -
          1. ad_supported
          2. premium
          3. none
        2. Defaults to none

      14. service_type -

        1. Values- 
          1. on_demand
          2. programmed
          3. none
        2. Defaults to none

      15. content_type -

        1. Values - 
          1. audio
          2. video
          3. none
        2. Defaults to none

      16. format -

        1. Values -
          1. digital
          2. physical
          3. none
        2. Defaults to none




    • Related Articles

    • How do I use the interactive Next-Gen API documentation?

      If you have an active "Luminate Data" account with access to the Music Connect API, you can explore the API here. In order to use the different endpoints, you need to authorize: Click on the first section for the POST /auth endpoint on the left side ...

    • Luminate Next-Gen Connect API Welcome Letter

      Your Luminate Next-Gen Connect API access is live! Here are some materials to help you get started! API Documentation in SwaggerHub FAQ on Data Definitions: What do the different acronyms mean? FAQ on Authorization: How do I use the interactive ...

    • How do I get an API key?

      To get an API key - please contact: Aurélie Nuttall: anuttall@luminatedata.com

    • How do I make a Next-Gen API call?

      The Next-Gen API uses get request instead of post request. This host a whole new set of parameter's and data that we can grab quickly in a new method. To build a URL you will always use the base URL of https://api.luminatedata.com/ To add onto this ...

    • What is the NEARS genre in the Luminate Genres group?

      In the Luminate Genres grouping, which can be used when accessing the Report Builder and the Analysis tool, there is a genre called NEARS. NEARS stands for: Nature Noise Effects Ambient Relaxation Sounds Please feel free to bring any questions to our ...

    • Popular Articles

    • Welcome to the all new Luminate Music Platform, Connect!

      Luminate is the preeminent entertainment data and insights company, unleashing access to the most essential, objective, and trustworthy information across music, film and television, with data compiled from hundreds of verified sources. Today, the ...

    • Luminate Next Gen Connect Overview

      For a quick overview of Luminate's Next Gen Connect please check out the video below! As the platform evolves this video will update to reflect the current status and features. So please bookmark and check back!

    • How do I get my music tracked by Luminate Data?

      Luminate Data tracks sales, streaming, and in North America, radio airplay. You must register your ISRC, UPC/EAN, and encode your music to be fully tracked. The registration process will take 2-3 business days. We can check if your registration was ...

    • Analysis Intro

      See below for a quick overview of the Analysis module in Luminate Music: Click here for more details on the Analysis module in Luminate Music.

    • Activity By Location (Country) Intro

      See below for a quick overview of the Activity by Location module for an Artist, Song, or Release Group in Luminate Music: Click here for more details on Activity By Location module in Luminate Music.