NAV Navbar
python shell
  • Music, meet AI.
  • Live chat @ Gitter
  • Special note to demo users
  • SDKs
  • Authentication / API Keys
  • Metadata
  • Search
  • Discovery & A.I. search (new!)
  • Personalization (alpha)
  • A.I. Music Analyzer
  • Batch Integration (new!)
  • Music, meet AI.

    Welcome to our A.I. Music API: the world's smartest music A.I. technology that we've pioneered here at Galiboo!

    With this Music Intelligence API, you can

    Powered by cutting-edge artificial intelligence capable of understanding music like humans, our technology will create amazing musical experiences for your users that were simply impossible before.

    Explore, and have fun!

    Live chat @ Gitter

    Got questions or wanna chat about our API? Or maybe even share what you're working on with other developers?

    Come hang out with us & other developers online, at https://gitter.im/galiboo/Lobby!

    Special note to demo users

    For users with demo API keys, we've loaded a fairly diverse, yet small, catalog of about 20K+ tracks into our backend system, to help you get a better sense of our technology. As a result, all of the tracks that are available via our demo API (e.g. results from the search, metadata, discovery, personalization endpoints) will only be chosen from this very small catalog of tracks.

    Please note that this may result in limited results, since we have not included every track ever released into our demo catalog (but rather, only a small subset of ~20K of them). Furthermore, the tracks recommended via our personalization endpoint will also limited to the 20K+ demo tracks. Nevertheless, you should be able to get a good idea of the power of our technology as you explore this demo.

    Upon signing up with us, however, we'll replace the demo catalog that is served via our API with the entire music catalog for your account, which will be integrated & synced with our technology as your catalog continues to grow over time!

    SDKs

    We currently have the following SDKs for accessing our Music API.

    Python - https://github.com/galiboo/galiboo-python - pip install galiboo

    Authentication / API Keys

    To send authorized requests to our API, use this code:

    from galiboo import Galiboo # Needs to be installed via: pip install galiboo
    galiboo_client = Galiboo("<your api key>")
    
    # In the shell, you can just pass the 'token' query parameter with each request
    curl
      "<api endpoint goes here>?token=<your api key>"
    

    Galiboo uses API keys to allow access to our Music API.

    If you don't have a key yet, you can get one at https://galiboo.com.

    To authorize your API requests, simply include the token query parameter in all API requests.

    Metadata

    Get metadata for tracks

    from galiboo import Galiboo
    
    galiboo = Galiboo("<YOUR API KEY>")
    
    print galiboo.track.metadata("5a419ed78cc3d0d2d4249ebb") # Charlie Puth's "Attention"
    
    curl 
      -H "content-type: application/json"
      http://secure.galiboo.com/api/metadata/tracks/<track_id>/?token=<your_key_goes_here>
    

    Make sure to replace track_id with the id of the track you would like to get metadata for.

    Example response (for this example, we're getting the metadata for Charlie Puth's hit song, "Attention"):

    {
      "_id": "5a419ed78cc3d0d2d4249ebb", 
      "analysis": {
        "acousticness": 0.20269793272018433, 
        "danceability": 0.6844576001167297, 
        "energy": 0.6664317846298218, 
        "instrumentalness": 0.08378501236438751, 
        "smart_tags": {
          "overall_predictions": {
            "Emotion-Arousing_/_Awakening": 0.037827033549547195, 
            "Emotion-Calming_/_Soothing": 0.05083180591464043, 
            "Emotion-Carefree_/_Lighthearted": 0.01567186787724495, 
            "Emotion-Cheerful_/_Festive": 0.014645703136920929, 
            "Emotion-Emotional_/_Passionate": 0.04763283580541611, 
            "Emotion-Laid-back_/_Mellow": 0.054663557559251785, 
            "Emotion-Light_/_Playful": 0.0154178561642766, 
            "Emotion-Loving_/_Romantic": 0.016411077231168747, 
            "Emotion-Pleasant_/_Comfortable": 0.0405605286359787, 
            "Emotion-Positive_/_Optimistic": 0.0094501543790102, 
            "Emotion-Powerful_/_Strong": 0.04072891175746918, 
            "Emotion-Tender_/_Soft": 0.021174278110265732, 
            "Emotion-Touching_/_Loving": 0.007727129850536585, 
            // probabilities for a lot more tags (not shown here)...
          }, 
          "segment_predictions": [
            {
              "Emotion-Arousing_/_Awakening": 0.04864450916647911, 
              "Emotion-Calming_/_Soothing": 0.0317840576171875, 
              "Emotion-Carefree_/_Lighthearted": 0.018668802455067635, 
              "Emotion-Cheerful_/_Festive": 0.013143418356776237, 
              "Emotion-Emotional_/_Passionate": 0.05765901133418083, 
              // ...
              "time_bounds": {
                "end": 6.8608, 
                "start": 0.0
              }
            }, 
            {
              "Emotion-Arousing_/_Awakening": 0.0458233468234539, 
              "Emotion-Calming_/_Soothing": 0.03387957811355591, 
              "Emotion-Carefree_/_Lighthearted": 0.018653681501746178, 
              "Emotion-Cheerful_/_Festive": 0.01171030756086111, 
              "Emotion-Emotional_/_Passionate": 0.06127491593360901, 
              // ...
              "time_bounds": {
                "end": 24.1664, 
                "start": 6.8608
              }
            },
            // ...
          ]
        }, 
        "tags": {
          "a_blues_song_form": 1.0037427273346111e-05, 
          "a_brass_horn_ensemble": 1.903908014355693e-05, 
          "a_breathy_female_lead_vocalist": 2.991182918776758e-05, 
          "a_breathy_male_lead_vocalist": 8.620150038041174e-05, 
          "a_brisk_swing_feel": 1.0442469289273504e-07, 
          "a_bumpin'_kick_sound": 0.010785230435431004, 
          "a_busy_bass_line": 0.006461316719651222, 
          "a_busy_horn_section": 0.003071569139137864, 
          "a_contrapuntal_melodic_presentation": 1.643851135213481e-07, 
          "a_deep_voice": 0.0012636446626856923, 
          // ...
        }, 
        "valence": 0.6371622085571289
      }, 
      "artists": [
        {
          "_id": "5a43dfbec3de0d102316497e", 
          "external_ids": {
            "spotify": "6VuMaDnrHyPL1p4EHjYLi7"
          }, 
          "name": "Charlie Puth"
        }
      ], 
      "audio_url": "https://storage.googleapis.com/gb_spotify20k/spotify_preview_audios/4iLqG9SeJSnt0cSPICSjxv.mp3", 
      "external_ids": {
        "spotify": "4iLqG9SeJSnt0cSPICSjxv"
      }, 
      "success": true, 
      "title": "Attention"
    }
    

    This endpoint retreives the emotions and other important metadata (energy, danceability, etc.) for the given track.

    HTTP Request

    GET http://secure.galiboo.com/api/metadata/tracks/<track_id>/

    Response

    Here's a brief description of the fields in a response that would typically be returned from this endpoint.

    Get metadata for artists

    from galiboo import Galiboo
    galiboo_client = Galiboo("<your api key>")
    
    charlie_puth = galiboo_client.artist.metadata("5a43dfbec3de0d102316497e")
    
    print charlie_puth['tracks']
    
    curl 
      -H "content-type: application/json"
      "http://secure.galiboo.com/api/metadata/artists/<artist_id>/?token=<your_key_goes_here>" 
    

    Example response (for this example, we're getting the metadata for Charlie Puth):

    {
      "_id": "5a43dfbec3de0d102316497e", 
      "external_ids": {
        "spotify": "6VuMaDnrHyPL1p4EHjYLi7"
      }, 
      "name": "Charlie Puth", 
      "num_tracks": 8, 
      "success": true, 
      "tracks": [
        {
          "_id": "5a419ed78cc3d0d2d4249ebb", 
          "analysis_url": "/api/metadata/tracks/5a419ed78cc3d0d2d4249ebb/", 
          "artists": [
            {
              "_id": "5a43dfbec3de0d102316497e", 
              "external_ids": {
                "spotify": "6VuMaDnrHyPL1p4EHjYLi7"
              }, 
              "name": "Charlie Puth"
            }
          ], 
          "audio_url": "https://storage.googleapis.com/gb_spotify20k/spotify_preview_audios/4iLqG9SeJSnt0cSPICSjxv.mp3", 
          "external_ids": {
            "spotify": "4iLqG9SeJSnt0cSPICSjxv"
          }, 
          "title": "Attention"
        }, 
        {
          "_id": "5a41d6798cc3d0d2d42b8652", 
          "analysis_url": "/api/metadata/tracks/5a41d6798cc3d0d2d42b8652/", 
          "artists": [
            {
              "_id": "5a43dfbec3de0d102316497e", 
              "external_ids": {
                "spotify": "6VuMaDnrHyPL1p4EHjYLi7"
              }, 
              "name": "Charlie Puth"
            }, 
            {
              "_id": "5a43dfcbc3de0d1023164c51", 
              "external_ids": {
                "spotify": "6JL8zeS1NmiOftqZTRgdTz"
              }, 
              "name": "Meghan Trainor"
            }
          ], 
          "audio_url": "https://storage.googleapis.com/gb_spotify20k/spotify_preview_audios/7rl1z4j7MurMDnn9rHh4M2.mp3", 
          "external_ids": {
            "spotify": "7rl1z4j7MurMDnn9rHh4M2"
          }, 
          "title": "Marvin Gaye (feat. Meghan Trainor)"
        }, 
        // ...
      ]
    }
    

    This endpoint retreives the metadata for the given artist.

    HTTP Request

    GET http://secure.galiboo.com/api/metadata/artists/<artist_id>/

    Query Parameters

    Parameter Default Description
    token None Your API key
    include_tracks true Indicates whether to include the tracks and num_tracks properties in the response

    Search

    Search for artists

    from galiboo import Galiboo
    galiboo_client = Galiboo("<your api key>")
    
    # Let's search for some relaxing music
    artist = "Camila Cabello"
    artists = galiboo_client.artist.get(artist)
    
    curl 
      -H "content-type: application/json"
      "http://secure.galiboo.com/api/metadata/artists/search/?token=<your_key_goes_here>&artist=<artist name goes here>"
    

    Example response (for this example, we are searching for the artist, Camila Cabello):

    {
      "num_results": 1, 
      "results": [
        {
          "_id": "5a43df47c3de0d1023163470", 
          "external_ids": {
            "spotify": "4nDoRrQiYLoBzwC5BhVJzF"
          }, 
          "name": "Camila Cabello", 
          "score": 1.5
        }
      ], 
      "success": true
    }
    

    This endpoint searches our index for artists that match your search criteria. This can be useful for retrieving the ids of artists by their name, for example, which can then be used for the other API endpoints.

    HTTP Request

    GET http://secure.galiboo.com/api/metadata/artists/search/

    Query Parameters

    Parameter Default Description
    token None Your API key
    artist None The name of the artist
    limit 10 The maximum number of search results to return
    page 1 The page of the search result to return

    Search for tracks

    from galiboo import Galiboo
    galiboo_client = Galiboo("<your api key>")
    
    # Let's search for Camila Cabello's Havana
    track = "Havana"
    tracks = galiboo_client.track.get(track=track)
    
    curl 
      -H "content-type: application/json"
      "http://secure.galiboo.com/api/metadata/tracks/search/?token=<your_key_goes_here>&track=<track title goes here>"
    
    # or ...
    
    curl 
      -H "content-type: application/json"
      "http://secure.galiboo.com/api/metadata/tracks/search/?token=<your_key_goes_here>&artist=<artist name goes here>"
    

    Example response (for this example, we are searching for Camila Cabello's "Havana" track):

    {
      "num_results": 1, 
      "results": [
        {
          "_id": "5a419db18cc3d0d2d42490fa", 
          "analysis_url": "/api/metadata/tracks/5a419db18cc3d0d2d42490fa/", 
          "artists": [
            {
              "_id": "5a43df47c3de0d1023163470", 
              "external_ids": {
                "spotify": "4nDoRrQiYLoBzwC5BhVJzF"
              }, 
              "name": "Camila Cabello"
            }, 
            {
              "_id": "5a43dfddc3de0d1023164fca", 
              "external_ids": {
                "spotify": "50co4Is1HCEo8bhOyUWKpn"
              }, 
              "name": "Young Thug"
            }
          ], 
          "audio_url": "https://storage.googleapis.com/gb_spotify20k/spotify_preview_audios/0ofbQMrRDsUaVKq2mGLEAb.mp3", 
          "external_ids": {
            "spotify": "0ofbQMrRDsUaVKq2mGLEAb"
          }, 
          "score": 1.1, 
          "title": "Havana"
        }
      ], 
      "success": true
    }
    

    This endpoint searches our index for tracks that match your search criteria. This can be useful for retrieving the ids of tracks by their name, for example, which can then be used for the other API endpoints (e.g. recommendations, finding similar tracks, etc).

    HTTP Request

    GET http://secure.galiboo.com/api/metadata/tracks/search/

    Query Parameters

    Parameter Default Description
    token None Your API key
    track None The title of the track
    artist None The name of the artist
    limit 10 The maximum number of search results to return
    page 1 The # of the page in the search result to return

    Discovery & A.I. search (new!)

    A.I. search for tracks (alpha)

    Search for music with natural language queries, & our music A.I. will return the relevant music tracks within seconds, automagically.

    from galiboo import Galiboo
    galiboo_client = Galiboo("<your api key>")
    
    # Let's search for some relaxing music
    query = "soft, piano tunes"
    tracks = galiboo_client.track.smart_search(query)
    
    curl 
      -H "content-type: application/json" 
      -G http://secure.galiboo.com/api/discover/tracks/smart_search/?token=<your_key_goes_here>&q=<your query>
    

    Example response:

    {
        "num_results": 10,
        "results": [
          {
            "_id": "5a41d3bb8cc3d0d2d42b6c80",
            "artists": [
                {
                    "_id": "5a3fee5dd836490c1872383e",
                    "external_ids": {
                      "spotify": "7vNcTk9TgKF0qDsS87nWGE"
                    },
                    "name": "David Sanborn"
                }
            ],
            "audio_url": "https://storage.googleapis.com/gb_spotify20k/spotify_preview_audios/6P09coloxpwV36qO2qjMhY.mp3",
            "external_ids": {
              "spotify": "6P09coloxpwV36qO2qjMhY"
            },
            "title": "One Hundred Ways"
          }, 
          {
            "_id": "5a41d8558cc3d0d2d42ba081",
            "artists": [
                {
                    "_id": "5a41d8558cc3d0d2d42ba07d",
                    "external_ids": {
                      "spotify": "3yroTvZKrVMjmu5yufiWJG"
                    },
                    "name": "André Ward"
                }
            ],
            "audio_url": "https://storage.googleapis.com/gb_spotify20k/spotify_preview_audios/79x2Lkq33VN2rQdrs9i6h6.mp3",
            "external_ids": {
              "spotify": "79x2Lkq33VN2rQdrs9i6h6"
            },
            "title": "City Vibe"
          },
          {
            "_id": "5a3fd3fcd836490c187101f7",
            "artists": [
                {
                    "_id": "5a3fd3c4d836490c1870ff97",
                    "external_ids": {
                      "spotify": "0djOiFh4VBdH2zXqJOvEnn"
                    },
                    "name": "Hamilton"
                }
            ],
            "audio_url": "https://storage.googleapis.com/gb_spotify20k/spotify_preview_audios/104Rq6Oh9cRttOFKVPiVmo.mp3",
            "external_ids": {
              "spotify": "104Rq6Oh9cRttOFKVPiVmo"
            },
            "title": "Heroes - Acoustic Version"
          }
          // ...
        ],
        "success": true
    }
    

    This endpoint searches for tracks that are relevant to the given natural language query. Since our A.I. understands music like humans, it's able to search for tracks based on their audio, without using their titles, manually-curated tags, etc.

    HTTP Request

    GET http://secure.galiboo.com/api/discover/tracks/smart_search/

    Query Parameters

    Parameter Default Description
    token None Your API key
    threshold 0.6 Higher threshold values increase precision at the cost of potentially narrowing down the number of results, and vice versa
    q None The natural language search query
    count 10 The maximum number of tracks to return per page
    page 1 The page of results to return

    Find tracks by tags

    from galiboo import Galiboo
    galiboo_client = Galiboo("<your api key>")
    
    # Let's find some nice music for doing focus work
    query = {
        "energy" : 0.25,
        "smart_tags" : {
             "Emotion-Calming_/_Soothing" : 0.9
        }
        # etc. (see our API docs for more info)
    }
    
    tracks = galiboo_client.track.search_by_tags(query)
    print tracks
    
    curl 
      -H "content-type: application/json" http://secure.galiboo.com/api/discover/tracks/find/?token=<your_key_goes_here> 
      --data '{your_query}'
    

    Example response (for this example, we're trying to find soothing tracks with some low energy):

    {
      "num_results": 10, 
      "results": [
        {
          "_id": "5a3fac6cd836490c186f1e6c", 
          "analysis_url": "/api/metadata/tracks/5a3fac6cd836490c186f1e6c/", 
          "artists": [
            {
              "_id": "5a3fac57d836490c186f1d7a", 
              "external_ids": {
                "spotify": "0YC192cP3KPCRWx8zr8MfZ"
              }, 
              "name": "Hans Zimmer"
            }
          ], 
          "audio_url": "https://storage.googleapis.com/gb_spotify20k/spotify_preview_audios/5vgIiJVCKx20m0RgwGNMEY.mp3", 
          "external_ids": {
            "spotify": "5vgIiJVCKx20m0RgwGNMEY"
          }, 
          "title": "Burning Secret: Suite - From \"A World Apart\""
        },
        {
          "_id": "5a3faed0d836490c186f39bb", 
          "analysis_url": "/api/metadata/tracks/5a3faed0d836490c186f39bb/", 
          "artists": [
            {
              "_id": "5a3faecad836490c186f3984", 
              "external_ids": {
                "spotify": "0kVNa1qBak8arcwcUeLu90"
              }, 
              "name": "Sleepdealer"
            }
          ], 
          "audio_url": "https://storage.googleapis.com/gb_spotify20k/spotify_preview_audios/18ARUyYMqmBfXbp1EX1K7f.mp3", 
          "external_ids": {
            "spotify": "18ARUyYMqmBfXbp1EX1K7f"
          }, 
          "title": "Astoria"
        }
        // ...
      ], 
      "success": true
    }
    

    This endpoint finds tracks that are musically close to the tag values that you specify. This can come in handy for many different tasks, such as curating a special playlist with specific types of tracks (ie. mellow, relaxing songs), for example.

    HTTP Request

    POST http://secure.galiboo.com/api/discover/tracks/find/

    Query Parameters

    Parameter Default Description
    token None Your API key
    threshold 0.6 Higher threshold values increase precision at the cost of potentially narrowing down the number of results, and vice versa
    limit 10 The maximum number of tracks to return per page
    page 1 The page of results to return

    POST Request JSON body

    A JSON dictionary containing query tags and their values, as shown in the examples.

    Find similar tracks

    from galiboo import Galiboo
    galiboo_client = Galiboo("<your api key>")
    
    # Let's find similar tracks to Coldplay's Viva la Vida
    similar_tracks = galiboo_client.track.search_by_similar("5a3fc326d836490c18703e3f")
    
    print similar_tracks
    
    curl 
      -H "content-type: application/json"
      "http://secure.galiboo.com/api/discover/tracks/<track_id>/similar/?token=<your_key_goes_here>"
    

    Example response (for this demo, we're looking for tracks in the demo catalog that are similar to Camila Cabello's "Havana"):

    {
      "num_results": 15, 
      "results": [
        {
          "_id": "5a41c5a68cc3d0d2d42af350", 
          "analysis_url": "/api/metadata/tracks/5a41c5a68cc3d0d2d42af350/", 
          "artists": [
            {
              "_id": "5a43dfb1c3de0d102316469f", 
              "external_ids": {
                "spotify": "7JwNWaTv4y9WNJCihQFHpv"
              }, 
              "name": "alayna"
            }, 
            {
              "_id": "5a43dfb1c3de0d10231646a0", 
              "external_ids": {
                "spotify": "3EpmmPtV7DduqNmeqaADIm"
              }, 
              "name": "Astronomyy"
            }
          ], 
          "audio_url": "https://storage.googleapis.com/gb_spotify20k/spotify_preview_audios/3ykujidUtB16GxCQgPU1sz.mp3", 
          "external_ids": {
            "spotify": "3ykujidUtB16GxCQgPU1sz"
          }, 
          "title": "Falling Autumn"
        }, 
        {
          "_id": "5a41f7408cc3d0d2d42d3d76", 
          "analysis_url": "/api/metadata/tracks/5a41f7408cc3d0d2d42d3d76/", 
          "artists": [
            {
              "_id": "5a43dfbdc3de0d1023164954", 
              "external_ids": {
                "spotify": "69GGBxA162lTqCwzJG5jLp"
              }, 
              "name": "The Chainsmokers"
            }, 
            {
              "_id": "5a43df75c3de0d1023163cba", 
              "external_ids": {
                "spotify": "26VFTg2z8YR0cCuwLzESi2"
              }, 
              "name": "Halsey"
            }
          ], 
          "audio_url": "https://storage.googleapis.com/gb_spotify20k/spotify_preview_audios/7BKLCZ1jbUBVqRi2FVlTVw.mp3", 
          "external_ids": {
            "spotify": "7BKLCZ1jbUBVqRi2FVlTVw"
          }, 
          "title": "Closer"
        }
        // ...
      ], 
      "success": true
    }
    

    This endpoint finds tracks in the catalog that are musically similar to the specified track, as felt by humans. This could be especially useful in a radio session, for example, when a user would prefer to listen to a stream of songs that sound similar.

    HTTP Request

    GET http://secure.galiboo.com/api/discover/tracks/<track_id>/similar/

    Query Parameters

    Parameter Default Description
    token None Your API key
    count 15 The number of similar tracks to search for

    Search by audio (new!)

    # TODO: Please that this API endpoint is not yet supported in our official Python client library, but will be very soon!
    
    import requests
    
    api_key = "<your api key>"
    
    # Let's find tracks similar to the audio at a url
    search_audio_url = "https://storage.googleapis.com/gb_spotify20k/spotify_preview_audios/4iLqG9SeJSnt0cSPICSjxv.mp3"
    
    response = requests.post("https://secure.galiboo.com/api/discover/tracks/search_by_audio/",
                              params = {'token' : api_key}, json = {'url' : search_audio_url}).json()
    print response["results"]
    
    # Or, let's find tracks similar to an audio file
    audio_file = open('<path to local audio file>')
    
    response = requests.post("https://secure.galiboo.com/api/discover/tracks/search_by_audio/",
                              params = {'token' : api_key}, files = {'file' : audio_file}).json()
    
    print response["results"]
    
    # Search for music in our catalog that's similar to an audio file (located at a URL)
    curl 
      -H "content-type: application/json" http://secure.galiboo.com/api/discover/tracks/search_by_audio/?token=<your_key_goes_here> 
      --data '{"url": "<your url>"}'
    

    Example response:

    {
      "num_results": 10, 
      "results": [
        {
          "_id": "5a3fac6cd836490c186f1e6c", 
          "audio_url": "https://storage.googleapis.com/gb_spotify20k/spotify_preview_audios/5vgIiJVCKx20m0RgwGNMEY.mp3", 
        },
        {
          "_id": "5a3faed0d836490c186f39bb", 
          "audio_url": "https://storage.googleapis.com/gb_spotify20k/spotify_preview_audios/18ARUyYMqmBfXbp1EX1K7f.mp3", 
        }
        // ...
      ], 
      "success": true
    }
    

    This endpoint searches for tracks in your (or our) catalog that are musically similar to a given audio file. This can be helpful for many different cases, such as finding similar music in a licensed catalog of tracks, etc.

    HTTP Request

    POST http://secure.galiboo.com/api/discover/tracks/search_by_audio/

    Query Parameters

    Parameter Default Description
    token None Your API key
    count 10 The maximum number of results to return

    POST Request JSON body

    A JSON dictionary containing either an audio url or an audio file.

    Personalization (alpha)

    This family of API endpoints takes care of the personalization end of things, such as extracting your users' music tastes, recommending them music, etc.

    Add a new user

    import requests
    
    internal_user_id = "<your user's internal id (as saved in your service) goes here>"
    
    user = {
        '_id' : internal_user_id
    }
    
    res = requests.post('http://secure.galiboo.com/api/personalization/users/new/', 
             params={'token' : '<your_key_goes_here>'}, json = user)
    
    print res.json()
    
    curl 
      -H "Content-Type: application/json"
      -d '{"_id" : "(user id, as saved in your service, goes here)"}'
      "http://secure.galiboo.com/api/personalization/users/new/?token=<your_key_goes_here>"
    

    Example response (for this example, let's register a new user with id 'test' from your service):

    {
      "client_user_id": "test", 
      "galiboo_user_id": "5a78e59456296c4eda8e9bf0", 
      "success": true
    }
    

    This endpoint enables you to add your service's users in our backend, in order to make use of our powerful personalization features for them.

    HTTP Request

    POST http://secure.galiboo.com/api/personalization/users/new/

    POST JSON Data Parameters

    Parameter Default Description
    _id None The unique id of the user as saved in your service (as a string)

    Response

    Here's a brief description of the fields in a response that would typically be returned from this endpoint.

    Add a user event

    import requests, datetime
    
    user_id = "<your user's galiboo id goes here>"
    sample_track_id = "5a41cdf48cc3d0d2d42b3d8c" # TLC's 'Haters' song
    
    # An event stating that the user listened to TLC's "Haters" track
    event = {
        'timestamp' : datetime.datetime.utcnow().isoformat(),
        'type' : 'listen',
        'object' : {
            'type' : 'track',
            'id' : sample_track_id
        }
    }
    
    # Optional
    event['meta'] = {
        'duration_ratio' : 0.9 # The user listened to 90% of the whole track
    }
    
    # Optional (helps our AI learn about the user's behavior and produce more intelligent recommendations)
    event['context'] = {
        "activity" : "running"
    }
    
    res = requests.post('http://secure.galiboo.com/api/personalization/users/' + user_id + '/events/new/', 
                            params={'token' : '<your_key_goes_here>'}, json = event)
    
    print res.json()
    
    curl
      -H "Content-Type: application/json"
      -d '{"context": {"activity": "running"},"meta": {"duration_ratio": 0.9},"object": {"id":"5a41cdf48cc3d0d2d42b3d8c", "type": "track"},"timestamp": "2018-01-08T10:11:27.703436","type": "listen"}'
      "http://secure.galiboo.com/api/personalization/users/<user_id>/events/new/?token=<your_key_goes_here>"
    

    Example response (for this example, let's register a new user listen event from your service):

    {
      "event_id": "5a78e78256296c4eda8e9bf1", 
      "success": true
    }
    

    This endpoint allows you to notify our live A.I. recommendation engine of user events (such as listens, skips, etc.) as they happen, enabling our technology to instantly adapt and provide smarter recommendations automagically, with no delay.

    HTTP Request

    POST http://secure.galiboo.com/api/personalization/users/<user_id>/events/new/

    POST JSON Data Parameters

    Parameter Default Description
    timestamp None The time of the event, as a string in ISO-8601 format
    type None The type of the event; Must be one of: listen, skip, like, dislike, follow, unfollow, and block
    object None An JSON object desribing the event's object (e.g. the object of a listen event would be a track, etc.). Must have 'id' and 'type' properties, where 'id' is the object's id and 'type' is one of the valid object types listed in the Object Types table below, corresponding to each event type.
    meta (optional) None A JSON object containing metadata for the specified event. See the Metadata Properties table below to see a list of valid metadata properties, corresponding to each event type.
    context (optional) None A JSON object containing information about the user's context during the event, such as location type (e.g. cafe, library, etc.) and activity (e.g. running, biking, etc.). See the Contextual Properties table below to see a list of valid contextual properties.

    Object Types

    Event type Valid object types
    listen track
    skip track
    like track, artist
    dislike track, artist
    follow artist
    unfollow artist
    block track, artist

    Metadata Properties

    Event type Valid Metadata properties
    listen duration_ratio
    skip duration_ratio

    Contextual Properties

    Property Valid values
    location_type cafe, gym, library, park, office, home, other_or_unknown
    activity running, walking, biking, driving, other_or_unknown

    Response

    Here's a brief description of the fields in a response that would typically be returned from this endpoint.

    Get a user

    import requests
    
    user_id = "<your user's Galiboo id>"
    
    res = requests.get('http://secure.galiboo.com/api/personalization/users/' + user_id + '/', 
             params={'token' : '<your_key_goes_here>'})
    
    print res.json()
    
    curl
      -H "Content-Type: application/json"
      "http://secure.galiboo.com/api/personalization/users/(user_id_goes_here)/?token=<your_key_goes_here>"
    

    Example response (for this example, let's retrieve the user with id 'test' from your service):

    {
      "_id": "5a78e59456296c4eda8e9bf0", 
      "client_id": "5a73ae88f36d281a9f552f9b", 
      "client_user_id": "test", 
      "recent_tracks": [
        "5a41cdf48cc3d0d2d42b3d8c"
      ], 
      "success": true
    }
    

    This endpoint enables you to retrieve a user in your service, stored in our backend.

    HTTP Request

    GET http://secure.galiboo.com/api/personalization/users/<user_id>/

    Response

    Here's a brief description of the fields in a response that would typically be returned from this endpoint.

    Get a user's events

    import requests
    
    user_id = "<your user's Galiboo id>"
    
    res = requests.get('http://secure.galiboo.com/api/personalization/users/' + user_id + '/events/', 
             params={'token' : '<your_key_goes_here>'})
    
    print res.json()
    
    curl
      -H "Content-Type: application/json"
      "http://secure.galiboo.com/api/personalization/users/(user_id_goes_here)/events/?token=<your_key_goes_here>"
    

    Example response (for this example, let's retrieve the events for user with id 'test' from your service):

    {
      "events": [
        {
          "_id": "5a78e78256296c4eda8e9bf1", 
          "context": {
            "activity": "running"
          }, 
          "meta": {
            "duration_ratio": 0.9
          }, 
          "object": {
            "id": "5a41cdf48cc3d0d2d42b3d8c", 
            "type": "track"
          }, 
          "timestamp": "Mon, 08 Jan 2018 10:11:27 GMT", 
          "type": "listen", 
          "user_id": "5a78e59456296c4eda8e9bf0"
        }
      ], 
      "num_events": 1, 
      "success": true
    }
    

    This endpoint enables you to retrieve the events for a specific user in your service, stored in our backend.

    HTTP Request

    GET http://secure.galiboo.com/api/personalization/users/<user_id>/events/

    Get music recommendations

    import requests, json
    
    user_id = "<your user's Galiboo id>"
    
    params = {
      'token' : '<your_key_goes_here>',
      'seed_track' : '5a41cdf48cc3d0d2d42b3d8c' # TLC's 'Haters' track
    }
    
    # Optionally include the user's context to get recommendations
    context = {
      'activity' : 'running'
    }
    params['context'] = json.loads(context)
    
    res = requests.get('http://secure.galiboo.com/api/personalization/users/' + user_id + '/recommend_tracks/', 
             params = params)
    
    print res.json()
    
    curl
      -H "Content-Type: application/json"
      "http://secure.galiboo.com/api/personalization/users/<user_id>/recommend_tracks/?token=<your_key_goes_here>&seed_track=(seed_track_id)&seed_artist=(seed_artist_id)&context=(optional user's context object as a string)"
    

    Example response (for this example, let's get music recommendations for user 'test', based on the seed track, TLC's 'Haters'):

    {
      "num_recommendations": 10, 
      "recommendations": [
        {
          "_id": "5a41c5a68cc3d0d2d42af350", 
          "analysis_url": "/api/metadata/tracks/5a41c5a68cc3d0d2d42af350/", 
          "artists": [
            {
              "_id": "5a43dfb1c3de0d102316469f", 
              "external_ids": {
                "spotify": "7JwNWaTv4y9WNJCihQFHpv"
              }, 
              "name": "alayna"
            }, 
            {
              "_id": "5a43dfb1c3de0d10231646a0", 
              "external_ids": {
                "spotify": "3EpmmPtV7DduqNmeqaADIm"
              }, 
              "name": "Astronomyy"
            }
          ], 
          "audio_url": "https://storage.googleapis.com/gb_spotify20k/spotify_preview_audios/3ykujidUtB16GxCQgPU1sz.mp3", 
          "external_ids": {
            "spotify": "3ykujidUtB16GxCQgPU1sz"
          }, 
          "title": "Falling Autumn"
        }, 
        {
          "_id": "5a41c1418cc3d0d2d42acb89", 
          "analysis_url": "/api/metadata/tracks/5a41c1418cc3d0d2d42acb89/", 
          "artists": [
            {
              "_id": "5a41a0778cc3d0d2d424b127", 
              "external_ids": {
                "spotify": "3RqBeV12Tt7A8xH3zBDDUF"
              }, 
              "name": "Kelsea Ballerini"
            }
          ], 
          "audio_url": "https://storage.googleapis.com/gb_spotify20k/spotify_preview_audios/15f2G5ywkUcb5Qx1YEpvq6.mp3", 
          "external_ids": {
            "spotify": "15f2G5ywkUcb5Qx1YEpvq6"
          }, 
          "title": "Yeah Boy"
        }, 
        {
          "_id": "5a41a2748cc3d0d2d424cd61", 
          "analysis_url": "/api/metadata/tracks/5a41a2748cc3d0d2d424cd61/", 
          "artists": [
            {
              "_id": "5a41a2748cc3d0d2d424cd5d", 
              "external_ids": {
                "spotify": "2DORQjKJVYZMx9uu82UGtT"
              }, 
              "name": "Amy Shark"
            }
          ], 
          "audio_url": "https://storage.googleapis.com/gb_spotify20k/spotify_preview_audios/1rPCgtaIF0CyKRgAwhtpbF.mp3", 
          "external_ids": {
            "spotify": "1rPCgtaIF0CyKRgAwhtpbF"
          }, 
          "title": "Adore"
        }, 
        {
          "_id": "5a3fb312d836490c186f734f", 
          "analysis_url": "/api/metadata/tracks/5a3fb312d836490c186f734f/", 
          "artists": [
            {
              "_id": "5a3fb312d836490c186f734d", 
              "external_ids": {
                "spotify": "5yf4LGUS3v1FYFxcCMvRIV"
              }, 
              "name": "Damzky"
            }
          ], 
          "audio_url": "https://storage.googleapis.com/gb_spotify20k/spotify_preview_audios/5zosayxZGzrtgEu83oCgKu.mp3", 
          "external_ids": {
            "spotify": "5zosayxZGzrtgEu83oCgKu"
          }, 
          "title": "Hurt"
        },
        // ...
      ], 
      "success": true
    }
    

    This endpoint enables you to get music recommendations for a user in real-time, using our AI-powered personalization technology.

    HTTP Request

    GET http://secure.galiboo.com/api/personalization/users/<user_id>/recommend_tracks/

    Query Parameters

    Parameter Default Description
    token None Your API key
    seed_track None The seed track id
    seed_artist None The seed artist id
    context None An optional JSON object describing the user's context (in the same format as the context object passed in when registering a new user event)
    limit 10 The maximum number of recommendations to return

    A.I. Music Analyzer

    This family of API endpoints enables you to analyze any music audio file to extract its emotions and other important acoustic metadata using our A.I. music-understanding technology, on-demand.

    Analyze music from a URL

    from galiboo import Galiboo
    galiboo_client = Galiboo("<your api key>")
    
    # Let's analyze the audio at this URL
    audio_url = "https://storage.googleapis.com/gb_spotify20k/spotify_preview_audios/4iLqG9SeJSnt0cSPICSjxv.mp3"
    analysis = galiboo_client.track.ai_analyze(audio_url)
    
    print analysis
    
    curl 
      -H "content-type: application/json"
      http://secure.galiboo.com/api/analyzer/analyze_url/?url=(the url to the audio file)&token=<your_key_goes_here>
    

    Example response (for this example, let's try to analyze the music audio file at this link):

    {
      "acousticness": 0.16529494524002075, 
      "danceability": 0.6929585933685303, 
      "energy": 0.6751042604446411, 
      "instrumentalness": 0.12262986600399017, 
      "smart_tags": {
        "overall_predictions": {
          "Emotion-Angry_/_Agressive": 0.0031637405045330524, 
          "Emotion-Arousing_/_Awakening": 0.037827037274837494, 
          "Emotion-Calming_/_Soothing": 0.05083180591464043, 
          "Emotion-Carefree_/_Lighthearted": 0.01567186787724495, 
          "Emotion-Emotional_/_Passionate": 0.04763282090425491, 
          "Emotion-Exciting_/_Thrilling": 0.021920567378401756, 
          "Emotion-Happy": 0.014965914189815521, 
          // ...
        }, 
        "segment_predictions": [
          {
            "Emotion-Angry_/_Agressive": 0.0031637405045330524, 
            "Emotion-Arousing_/_Awakening": 0.037827037274837494, 
            "Emotion-Calming_/_Soothing": 0.05083180591464043, 
            "Emotion-Carefree_/_Lighthearted": 0.01567186787724495, 
            "Emotion-Emotional_/_Passionate": 0.04763282090425491, 
            "Emotion-Exciting_/_Thrilling": 0.021920567378401756, 
            "Emotion-Happy": 0.014965914189815521, 
            // ...
            "time_bounds": {
              "end": 6.8608, 
              "start": 0.0
            }
          }, 
          {
            "Emotion-Arousing_/_Awakening": 0.04582327976822853, 
            "Emotion-Calming_/_Soothing": 0.03387962281703949, 
            "Emotion-Carefree_/_Lighthearted": 0.018653688952326775, 
            "Emotion-Cheerful_/_Festive": 0.011710296384990215, 
            "Emotion-Emotional_/_Passionate": 0.061274923384189606, 
            "Emotion-Exciting_/_Thrilling": 0.018407059833407402, 
            "Emotion-Happy": 0.016545193269848824, 
            // ...
          },
          // ...
        ]
      }, 
      "tags": {
        "a_blues_song_form": 2.6463205358595587e-05, 
        "a_brass_horn_ensemble": 5.5146319937193766e-05, 
        "a_breathy_female_lead_vocalist": 7.17119692126289e-05, 
        "a_breathy_male_lead_vocalist": 0.00010172282782150432, 
        "a_brisk_swing_feel": 6.144405233499128e-07, 
        // ...
      }, 
      "valence": 0.635773777961731
    }
    

    This endpoint enables you to analyze a music audio file given its URL, using our A.I. music-understanding technology.

    HTTP Request

    GET http://secure.galiboo.com/api/analyzer/analyze_url/

    Query Parameters

    Parameter Default Description
    token None Your API key
    url None The URL of the audio file to analyze

    Analyze music from a YouTube URL

    from galiboo import Galiboo
    galiboo_client = Galiboo("<your api key>")
    
    # Let's analyze the audio at this URL
    youtube_video = "https://www.youtube.com/watch?v=nfs8NYg7yQM"
    analysis = galiboo_client.track.ai_analyze(youtube_video)
    
    print analysis
    
    curl
      -H "Content-Type: application/json"
      "http://secure.galiboo.com/api/analyzer/analyze_youtube/?url=(the url to the YouTube video)&token=<your_key_goes_here>"
    

    Example response (for this example, let's try to analyze the music in this Vevo music video for Charlie Puth's hit track, 'Attention'):

    {
      "acousticness": 0.11556543409824371, 
      "danceability": 0.7361493706703186, 
      "energy": 0.7121661901473999, 
      "instrumentalness": 0.13932456076145172, 
      "smart_tags": {
        "overall_predictions": {
          "Emotion-Angry_/_Agressive": 0.00037414784310385585, 
          "Emotion-Arousing_/_Awakening": 0.009032707661390305, 
          "Emotion-Bizarre_/_Weird": 0.005755786783993244, 
          "Emotion-Calming_/_Soothing": 0.07326637208461761, 
          "Emotion-Carefree_/_Lighthearted": 0.016115780919790268, 
          "Emotion-Cheerful_/_Festive": 0.006847914308309555, 
          "Emotion-Emotional_/_Passionate": 0.060022205114364624, 
          "Emotion-Exciting_/_Thrilling": 0.004365433938801289, 
          "Emotion-Happy": 0.010212373919785023, 
          "Emotion-Laid-back_/_Mellow": 0.0720716267824173, 
          "Emotion-Light_/_Playful": 0.01490783877670765, 
          "Emotion-Loving_/_Romantic": 0.05496947839856148,
          // ...
        }, 
        "segment_predictions": [
          {
            "Emotion-Angry_/_Agressive": 0.0009975236607715487, 
            "Emotion-Arousing_/_Awakening": 0.00997752882540226, 
            "Emotion-Bizarre_/_Weird": 0.009077725932002068, 
            "Emotion-Calming_/_Soothing": 0.07734066992998123, 
            // ...
            "time_bounds": {
              "end": 4.7274666666666665, 
              "start": 0.0
            }
          }, 
          {
            "Emotion-Angry_/_Agressive": 0.0002590988005977124, 
            "Emotion-Arousing_/_Awakening": 0.006544820498675108, 
            "Emotion-Bizarre_/_Weird": 0.004198519978672266, 
            "Emotion-Calming_/_Soothing": 0.07837198674678802, 
            "Emotion-Carefree_/_Lighthearted": 0.01784326694905758, 
            "Emotion-Cheerful_/_Festive": 0.0061309728771448135, 
            "Emotion-Emotional_/_Passionate": 0.06926513463258743, 
            "Emotion-Exciting_/_Thrilling": 0.0030543426983058453, 
            "Emotion-Happy": 0.011605112813413143, 
            "Emotion-Laid-back_/_Mellow": 0.07474061101675034, 
            "Emotion-Light_/_Playful": 0.015917405486106873, 
            "Emotion-Loving_/_Romantic": 0.04090088978409767, 
            // ...
          }, 
          // ...
        ]
      }, 
      "tags": {
        "a_blues_song_form": 1.2447139852156397e-06, 
        "a_brass_horn_ensemble": 1.3550161384046078e-06, 
        "a_breathy_female_lead_vocalist": 2.0741485059261322e-05, 
        "a_breathy_male_lead_vocalist": 6.391082024492789e-06, 
        "a_brisk_swing_feel": 1.0316570708823747e-08, 
        // ...
      }, 
      "valence": 0.6678715348243713
    }
    

    This endpoint enables you to analyze the music of a YouTube video given its URL, using our A.I. music-understanding technology.

    HTTP Request

    GET http://secure.galiboo.com/api/analyzer/analyze_youtube/

    Query Parameters

    Parameter Default Description
    token None Your API key
    url None The URL of the YouTube video with the music to analyze

    Batch Integration (new!)

    This family of API endpoints enables you to analyze large batches of music audio files (in the background) using our scalable, cloud-based A.I. technology.

    Schedule a Music Analysis Job

    from galiboo import Galiboo
    galiboo_client = Galiboo("<your api key>")
    
    # Let's schedule a job in Galiboo's cloud to analyze the audio at this URL
    audio_url = "https://storage.googleapis.com/gb_spotify20k/spotify_preview_audios/4iLqG9SeJSnt0cSPICSjxv.mp3"
    job = galiboo_client.track.analyze(audio_url)
    
    print job
    
    curl 
      -H "content-type: application/json"
      "http://secure.galiboo.com/api/integration/tracks/analyze/?url=(the url to the audio file)&token=<your_key_goes_here>"
    

    Example response

    {
      "job_id": "5b67723956296c1115fabcda",
      "status": "QUEUED",
      "success": true,
      "time_created": "Sun, 05 Aug 2018 21:55:05 GMT",
      "time_updated": "Sun, 05 Aug 2018 21:55:05 GMT",
      "url": "https://s3-eu-west-1.amazonaws.com/your_audio_file.mp3"
    }
    

    This endpoint will schedule a background job in our cloud to analyze the audio file at the given URL. Please note that, unlike our AI Analyzer API, the analysis will not be done within the cycle of the HTTP request. Rather, it will be batch processed in the background, and you can track the job's status using the job ID returned by this endpoint and the Job Status API endpoint below.

    HTTP Request

    GET http://secure.galiboo.com/api/integration/tracks/analyze/

    Query Parameters

    Parameter Default Description
    token None Your API key
    url None The URL of the audio file to analyze (must be publicly accessible)

    View a job's status

    from galiboo import Galiboo
    galiboo_client = Galiboo("<your api key>")
    
    # Let's get the status/results of an analysis job that we scheduled
    job_id = "5b8c17c9011610000bc2de67"
    job = galiboo_client.job.get(job_id)
    
    print job
    
    curl "http://secure.galiboo.com/api/integration/jobs/<job_id>/?token=<your_key_goes_here>"
    

    Example response

    {
      "job": {
        // This analysis object has the same structure as the ones returned by our metadata endpoints.
        "analysis": {
          "acousticness": 0.16527976095676422,
          "danceability": 0.6929667592048645,
          "energy": 0.6751201748847961,
          "instrumentalness": 0.12261679023504257,
          "smart_tags": {
            // ...
          },
          "tags": {
            // ..
          },
          "valence": 0.6357817053794861
        },
        "job_id": "5b67723956296c1115fabcda",
        "status": "SUCCESS",
        "time_completed": "Sun, 05 Aug 2018 21:55:52 GMT",
        "time_created": "Sun, 05 Aug 2018 21:55:05 GMT",
        "time_updated": "Sun, 05 Aug 2018 21:55:52 GMT",
        "url": "https://<your_audio_url>.mp3"
        },
        "success": true
    }
    

    This endpoint enables you to monitor the status of a music analysis job that you scheduled using our Batch Integration API.

    HTTP Request

    GET http://secure.galiboo.com/api/integration/jobs/<job_id>/

    Parameters

    Parameter Default Description
    token None Your API key
    job_id None The job ID returned by the previous API endpoint (this is a path parameter, not a query parameter)

    View all jobs

    from galiboo import Galiboo
    galiboo_client = Galiboo("<your api key>")
    
    # Let's get the status/results of all the analysis jobs that we scheduled
    jobs = galiboo_client.job.all()
    print jobs
    
    curl "http://secure.galiboo.com/api/integration/jobs/?token=<your_key_goes_here>"
    

    Example response

    {
        "jobs": [
            {
                "analysis_url": "/jobs/5b8c17c9011610000bc2de67/",
                "job_id": "5b8c17c9011610000bc2de67",
                "status": "SUCCESS",
                "time_completed": "Sun, 02 Sep 2018 17:03:07 GMT",
                "time_completed_isoformat": "2018-09-02T17:03:07.654000",
                "time_created": "Sun, 02 Sep 2018 17:03:05 GMT",
                "time_created_isoformat": "2018-09-02T17:03:05.335000",
                "time_updated": "Sun, 02 Sep 2018 17:03:07 GMT",
                "time_updated_isoformat": "2018-09-02T17:03:07.654000",
                "track_id": "KDo8m2UBu4iqZ3bU9CqT",
                "url": "https://storage.googleapis.com/gb_spotify20k/spotify_preview_audios/4iLqG9SeJSnt0cSPICSjxv.mp3"
            },
            {
                "analysis_url": "/jobs/5b8ae99252344300166f46b9/",
                "job_id": "5b8ae99252344300166f46b9",
                "status": "SUCCESS",
                "time_completed": "Sat, 01 Sep 2018 19:50:41 GMT",
                "time_completed_isoformat": "2018-09-01T19:50:41.267000",
                "time_created": "Sat, 01 Sep 2018 19:33:38 GMT",
                "time_created_isoformat": "2018-09-01T19:33:38.966000",
                "time_updated": "Sat, 01 Sep 2018 19:50:41 GMT",
                "time_updated_isoformat": "2018-09-01T19:50:41.267000",
                "track_id": "5a3faec9d836490c186f397b",
                "url": "https://storage.googleapis.com/gb_spotify20k/spotify_preview_audios/2oxbgAkN0nJhSz9ngSSXRL.mp3"
             }
        ],
        "page": 1,
        "page_size": 10,
        "success": true
    }
    

    This endpoint enables you to get a list of all the music analysis jobs that you've scheduled using our Batch Integration API.

    HTTP Request

    GET http://secure.galiboo.com/api/integration/jobs/

    Parameters

    Parameter Default Description
    token None Your API key
    show_progress false Whether to return some stats about the overall progress of all the music analysis jobs that you've submitted.
    page 1 The page of the results to return