Limiting results to a catalog

This tutorial shows how to limit results to artists that are in a particular partner catalog.

Details

The Echo Nest works with many partners that have their own APIs. Often, you will want to be able to limit the results to only those that are in a particular partner catalog. For instance, if you want to build a music recommender that works with Rdio, you will want to make sure that only artists in the Rdio catalog are returned by your recommender. Any artist method that returns a list of artists can be configured to only returned artists that are within a particular catalog. To do so, list the ID space as a bucket parameter to the method and set the limit parameter to be true. The limit parameter causes the results to be limited to any of the listed ID spaces or catalogs.

Example

Here's an example of limiting the results of the artist search command to the 7Digital artist catalog.

Example

Response

{
    "response": {
        "artists": [
            {
                "foreign_ids": [
                    {
                        "catalog": "7digital-US", 
                        "foreign_id": "7digital-US:artist:304"
                    }
                ], 
                "id": "ARH6W4X1187B99274F", 
                "name": "Radiohead"
            }
        ], 
        "status": {
            "code": 0, 
            "message": "Success", 
            "version": "4.2"
        }
    }
}
Similarly we can limit the results of an artist similarity call to the Rdio us streaming catalog like so.

Note that the rdio-us-streaming song catalog used in this example has been superceded by the rdio-US catalog

Example

Response

{
    "response": {
        "artists": [
            {
                "foreign_ids": [
                    {
                        "catalog": "rdio-us-streaming", 
                        "foreign_id": "rdio-us-streaming:artist:r86252"
                    }
                ], 
                "id": "ARN5NHX1187FB4F755", 
                "name": "The Smashing Pumpkins"
            }, 
            {
                "foreign_ids": [
                    {
                        "catalog": "rdio-us-streaming", 
                        "foreign_id": "rdio-us-streaming:artist:r101853"
                    }
                ], 
                "id": "ARS94L01187B9AD297", 
                "name": "Nerf Herder"
            }, 
            {
                "foreign_ids": [
                    {
                        "catalog": "rdio-us-streaming", 
                        "foreign_id": "rdio-us-streaming:artist:r138945"
                    }
                ], 
                "id": "AR6OJYP1187B9AE997", 
                "name": "Jimmy Eat World"
            }
        ], 
        "status": {
            "code": 0, 
            "message": "Success", 
            "version": "4.2"
        }
    }
}

Getting Hotttest Facebook artists

There are a number of artist methods that support the limit parameter, including artist/search, artist/similar and top_hottt. Here's an example of using the top_hottt method to retrieve the current hotttest artists that have Facebook pages.

Response

{
    "response": {
        "artists": [
            {
                "foreign_ids": [
                    {
                        "catalog": "facebook", 
                        "foreign_id": "facebook:artist:10376464573"
                    }
                ], 
                "hotttnesss": 1.0, 
                "id": "ARX6TAQ11C8A415850", 
                "name": "Lady Gaga"
            }, 
            {
                "foreign_ids": [
                    {
                        "catalog": "facebook", 
                        "foreign_id": "facebook:artist:6871006677"
                    }
                ], 
                "hotttnesss": 0.8574252, 
                "id": "ARSPUJF1187B9A14B8", 
                "name": "Death Cab for Cutie"
            }, 
            {
                "foreign_ids": [
                    {
                        "catalog": "facebook", 
                        "foreign_id": "facebook:artist:39677118233"
                    }
                ], 
                "hotttnesss": 0.85621773999999995, 
                "id": "AR03BDP1187FB5B324", 
                "name": "Britney Spears"
            }, 
            {
                "foreign_ids": [
                    {
                        "catalog": "facebook", 
                        "foreign_id": "facebook:artist:9770929278"
                    }
                ], 
                "hotttnesss": 0.85520379999999996, 
                "id": "AR7J9AP1187FB5BD64", 
                "name": "Adele"
            }, 
            {
                "foreign_ids": [
                    {
                        "catalog": "facebook", 
                        "foreign_id": "facebook:artist:95051637400"
                    }
                ], 
                "hotttnesss": 0.85188763999999995, 
                "id": "ARK9BHE1187FB3AC9D", 
                "name": "Pitbull"
            }, 
            {
                "foreign_ids": [
                    {
                        "catalog": "facebook", 
                        "foreign_id": "facebook:artist:6821255451"
                    }
                ], 
                "hotttnesss": 0.84998870000000004, 
                "id": "ARXWRR61187FB4BFF9", 
                "name": "My Morning Jacket"
            }, 
            {
                "foreign_ids": [
                    {
                        "catalog": "facebook", 
                        "foreign_id": "facebook:artist:242567287243"
                    }
                ], 
                "hotttnesss": 0.84956900000000002, 
                "id": "ARJHCSL123E29C21E8", 
                "name": "Bruno Mars"
            }, 
            {
                "foreign_ids": [
                    {
                        "catalog": "facebook", 
                        "foreign_id": "facebook:artist:10092511675"
                    }
                ], 
                "hotttnesss": 0.84832036, 
                "id": "ARKU3Z61187FB51DCA", 
                "name": "Rihanna"
            }, 
            {
                "foreign_ids": [
                    {
                        "catalog": "facebook", 
                        "foreign_id": "facebook:artist:5170395767"
                    }
                ], 
                "hotttnesss": 0.84237443999999995, 
                "id": "AR7C6G11187B9B4C1E", 
                "name": "Jennifer Lopez"
            }, 
            {
                "foreign_ids": [
                    {
                        "catalog": "facebook", 
                        "foreign_id": "facebook:artist:19855571496"
                    }
                ], 
                "hotttnesss": 0.83852135999999999, 
                "id": "ARVKJGO12086C15075", 
                "name": "LMFAO"
            }
        ], 
        "status": {
            "code": 0, 
            "message": "Success", 
            "version": "4.2"
        }
    }
}