NAV Navigation
Shell HTTP JavaScript Node.js Ruby Python Java Go

Qloo v0.0.2

Scroll down for code samples, example requests and responses. Select a language for code samples from the tabs above or the mobile navigation menu.

Qloo API, Universal Music Hackathon Edition

Base URLs:

Default

get__recs

Code samples

# You can also use wget
curl -X GET https://qsz08t9vtl.execute-api.us-east-1.amazonaws.com/production/recs?category=music%2Fartists&sample=8622A10A-B77C-49FE-9874-C740C0728E5C%2C8622A10A-B77C-49FE-9874-C740C0728E5D \
  -H 'Accept: application/json'


GET https://qsz08t9vtl.execute-api.us-east-1.amazonaws.com/production/recs?category=music%2Fartists&sample=8622A10A-B77C-49FE-9874-C740C0728E5C%2C8622A10A-B77C-49FE-9874-C740C0728E5D HTTP/1.1
Host: qsz08t9vtl.execute-api.us-east-1.amazonaws.com

Accept: application/json


var headers = {
  'Accept':'application/json'

};

$.ajax({
  url: 'https://qsz08t9vtl.execute-api.us-east-1.amazonaws.com/production/recs',
  method: 'get',
  data: '?category=music%2Fartists&sample=8622A10A-B77C-49FE-9874-C740C0728E5C%2C8622A10A-B77C-49FE-9874-C740C0728E5D',
  headers: headers,
  success: function(data) {
    console.log(JSON.stringify(data));
  }
})


const request = require('node-fetch');

const headers = {
  'Accept':'application/json'

};

fetch('https://qsz08t9vtl.execute-api.us-east-1.amazonaws.com/production/recs?category=music%2Fartists&sample=8622A10A-B77C-49FE-9874-C740C0728E5C%2C8622A10A-B77C-49FE-9874-C740C0728E5D',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});


require 'rest-client'
require 'json'

headers = {
  'Accept' => 'application/json'
}

result = RestClient.get 'https://qsz08t9vtl.execute-api.us-east-1.amazonaws.com/production/recs',
  params: {
  'category' => '[Category](#schemacategory)',
'sample' => 'array[string]'
}, headers: headers

p JSON.parse(result)


import requests
headers = {
  'Accept': 'application/json'
}

r = requests.get('https://qsz08t9vtl.execute-api.us-east-1.amazonaws.com/production/recs', params={
  'category': 'music/artists',  'sample': '8622A10A-B77C-49FE-9874-C740C0728E5C,8622A10A-B77C-49FE-9874-C740C0728E5D'
}, headers = headers)

print r.json()


URL obj = new URL("https://qsz08t9vtl.execute-api.us-east-1.amazonaws.com/production/recs?category=music%2Fartists&sample=8622A10A-B77C-49FE-9874-C740C0728E5C%2C8622A10A-B77C-49FE-9874-C740C0728E5D");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("GET");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());


package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Accept": []string{"application/json"},
        
    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("GET", "https://qsz08t9vtl.execute-api.us-east-1.amazonaws.com/production/recs", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

GET /recs

Get recommendations

Get recommendations based on a sample array.

Parameters

Parameter In Type Required Description
category query Category true The category to receive recommendations in.
sample query array[string] true The entities to base the recommendations on.
location query InputGeo false The location to base the recommendations on. This only applies to categories with geolocation data.
radius query Radius false The max distance from the location to base recommendations on. This only applies to categories with geolocation data.
records query integer false The number of records to return.
sort_by query string false Sort the result set by affinity score descending or distance ascending
prioritize_indomain query boolean false Use only in-domain samples when they exist, otherwise use all samples

Enumerated Values

Parameter Value
category books/books
category books/authors
category dining/restaurants
category fashion/brands
category film/movies
category music/artists
category travel/hotels
category tv/shows
sort_by affinity
sort_by distance

Example responses

200 Response

{
  "results": [
    {
      "name": "Beyonce",
      "id": "8622A10A-B77C-49FE-9874-C740C0728E5C",
      "location": {
        "latitude": 40.742306,
        "longitude": -74.003494
      },
      "popularity": 0.9999,
      "query": {
        "affinity": 0.0178,
        "distance": 1.5639
      }
    }
  ]
}

Responses

Status Meaning Description Schema
200 OK OK Inline
404 Not Found Entity not found Error
429 Too Many Requests Rate limit exceeded None

Response Schema

Status Code 200

Name Type Required Restrictions Description
» results [Recommendation] false none none
»» name string false none none
»» id EntityId(uuid) false none Qloo Entity ID
»» location Geo false none A Geolocation object
»»» latitude integer false none none
»»» longitude integer false none none
»» popularity integer false none none
»» query object false none none
»»» affinity integer false none none
»»» distance integer false none none

get__search

Code samples

# You can also use wget
curl -X GET https://qsz08t9vtl.execute-api.us-east-1.amazonaws.com/production/search \
  -H 'Accept: application/json'


GET https://qsz08t9vtl.execute-api.us-east-1.amazonaws.com/production/search HTTP/1.1
Host: qsz08t9vtl.execute-api.us-east-1.amazonaws.com

Accept: application/json


var headers = {
  'Accept':'application/json'

};

$.ajax({
  url: 'https://qsz08t9vtl.execute-api.us-east-1.amazonaws.com/production/search',
  method: 'get',

  headers: headers,
  success: function(data) {
    console.log(JSON.stringify(data));
  }
})


const request = require('node-fetch');

const headers = {
  'Accept':'application/json'

};

fetch('https://qsz08t9vtl.execute-api.us-east-1.amazonaws.com/production/search',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});


require 'rest-client'
require 'json'

headers = {
  'Accept' => 'application/json'
}

result = RestClient.get 'https://qsz08t9vtl.execute-api.us-east-1.amazonaws.com/production/search',
  params: {
  }, headers: headers

p JSON.parse(result)


import requests
headers = {
  'Accept': 'application/json'
}

r = requests.get('https://qsz08t9vtl.execute-api.us-east-1.amazonaws.com/production/search', params={

}, headers = headers)

print r.json()


URL obj = new URL("https://qsz08t9vtl.execute-api.us-east-1.amazonaws.com/production/search");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("GET");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());


package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Accept": []string{"application/json"},
        
    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("GET", "https://qsz08t9vtl.execute-api.us-east-1.amazonaws.com/production/search", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

GET /search

Search for an entity by name or property

Parameters

Parameter In Type Required Description
category query Category false The category to search against.
query query string false The text to search against.
location query InputGeo false The location to base the search on. This only applies to categories with geolocation data.
radius query Radius false The max distance from the location to base search on. This only applies to categories with geolocation data.
spotify_id query string false Spotify ID
allmusic_id query string false AllMusic ID
musicbrainz_id query string false MusicBrainz ID

Enumerated Values

Parameter Value
category books/books
category books/authors
category dining/restaurants
category fashion/brands
category film/movies
category music/artists
category travel/hotels
category tv/shows

Example responses

200 Response

{
  "results": [
    {
      "name": "Beyonce",
      "id": "8622A10A-B77C-49FE-9874-C740C0728E5C",
      "location": {
        "latitude": 40.742306,
        "longitude": -74.003494
      },
      "popularity": 0.9999,
      "query": {
        "affinity": 0.0178,
        "distance": 1.5639
      }
    }
  ]
}

Responses

Status Meaning Description Schema
200 OK OK Inline
404 Not Found No results Error
429 Too Many Requests Rate limit exceeded None

Response Schema

Status Code 200

Name Type Required Restrictions Description
» results [Recommendation] false none none
»» name string false none none
»» id EntityId(uuid) false none Qloo Entity ID
»» location Geo false none A Geolocation object
»»» latitude integer false none none
»»» longitude integer false none none
»» popularity integer false none none
»» query object false none none
»»» affinity integer false none none
»»» distance integer false none none

Schemas

InputGeo

[
  0
]

Geolocation in latitude, longitude

Properties

None

Radius

5

Radius parameter, in miles

Properties

Name Type Required Restrictions Description
anonymous integer false none Radius parameter, in miles

Category

"music/artists"

Qloo Categories

Properties

Name Type Required Restrictions Description
anonymous string false none Qloo Categories

Enumerated Values

Property Value
anonymous books/books
anonymous books/authors
anonymous dining/restaurants
anonymous fashion/brands
anonymous film/movies
anonymous music/artists
anonymous travel/hotels
anonymous tv/shows

EntityId

"8622A10A-B77C-49FE-9874-C740C0728E5C"

Qloo Entity ID

Properties

Name Type Required Restrictions Description
anonymous string(uuid) false none Qloo Entity ID

Geo

{
  "latitude": 40.742306,
  "longitude": -74.003494
}

A Geolocation object

Properties

Name Type Required Restrictions Description
latitude integer false none none
longitude integer false none none

Recommendation

{
  "name": "Beyonce",
  "id": "8622A10A-B77C-49FE-9874-C740C0728E5C",
  "location": {
    "latitude": 40.742306,
    "longitude": -74.003494
  },
  "popularity": 0.9999,
  "query": {
    "affinity": 0.0178,
    "distance": 1.5639
  }
}

A recommended entity

Properties

Name Type Required Restrictions Description
name string false none none
id EntityId false none none
location Geo false none none
popularity integer false none none
query object false none none
» affinity integer false none none
» distance integer false none none

Error

{
  "message": "Something went wrong"
}

Properties

Name Type Required Restrictions Description
message string false none none
Shell HTTP JavaScript Node.js Ruby Python Java Go