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 |