SuggestGrid REST API
SuggestGrid Rest Documentation
We will walk through how to get started with SuggestGrid Rest Documentation in three steps:
Getting Started
In this guide we will demonstrate how to display personalized recommendations on an existing Rest project.
We have a movie catalog Rest application, SuggestGridMovies, similar to IMDb. For logged in users we want to display movies that similar people viewed on movie pages. Let's implement this feature in five minutes with SuggestGrid!
1. Configuration
Once you sign up for SuggestGrid, you'll see your SUGGESTGRID_URL parameter on the dashboard in the format below:
http://{user}:{pass}@{region}.suggestgrid.space/{app-uuid}
You can authenticate your application using SUGGESTGRID_URL
environment variable like the example below:
$ export SUGGESTGRID_URL=http://{user}:{pass}@{region}.suggestgrid.space/{app-uuid}
```shell
$ curl -XGET $SUGGESTGRID_URL
# Status code: 200
{"uuid":"76650795-2bb2-4644-8dd7-dfe5e670d31c","version":"0.1.31","authentication":"private","subscription":"Basic","limitations":{"types":{"count":3,"limit":5},"actions":{"count":9,"limit":10000000}}}
Every recommendation logic needs to belong to a type.
For this demonstration we can create an implicit type named as views
.
This could be done either from the dashboard or with a snippet like this:
$ curl -XPUT $SUGGESTGRID_URL/v1/types/views
# Status code: 200
{"message":"Type `views` is created with `implicit` rating."}
2. Post actions
Once the type exists, let's start posting actions. We should invoke SuggestGrid client's when an user views an item in our application.
We can do this by putting the snippet below on the relevant point:
$ curl -XPOST $SUGGESTGRID_URL/v1/actions -d '{
"type": "views",
"user_id": "123",
"item_id": "456"
}'
# Status code: 201
{"message":"Action posted."}
$ curl -XPOST $SUGGESTGRID_URL/v1/actions -d '{
"type": "views",
"user_id": "123",
"item_id": "451"
}'
# Status code: 201
{"message":"Action posted."}
$ curl -XPOST $SUGGESTGRID_URL/v1/actions -d '{
"type": "views",
"user_id": "12",
"item_id": "451"
}'
# Status code: 201
{"message":"Action posted."}
The more actions SuggestGrid gets, more relevant and diverse its responses are.
3. Get recommendations
Finally, let's show "movies similar users viewed" on movie pages.
SuggestGrid needs recommendation models for returning recommendations. Model generation is scheduled in every 24 hours. In addition, instant model generations can be triggered on the dashboard.
Once the first model generated for 'views' type, recommendations could be get using a snippet like the following:
$ curl -XPOST $SUGGESTGRID_URL/v1/recommend/items -d '{
"type": "views",
"user_id": "12"
}'
# Status code: 200
{"items":[{"id":"451"},{"id":"456"}],"count":2}
Type Methods
Type methods are used for creating, getting, and deleting types. Refer to types for an overview.
Creates a Type
PUT /v1/types/{type} -d {type_request_body}
Creates a new type.
Creating an implicit type:
$ curl -XPUT $SUGGESTGRID_URL/v1/types/view -d '{
"rating" : "implicit"
}'
# Status code: 201
{"message":"Type view is created with implicit rating."}
or:
$ curl -XPUT $SUGGESTGRID_URL/v1/types/checkout
# Status code: 201
{"message":"Type checkout is created with implicit rating."}
Creating an explicit type:
$ curl -XPUT $SUGGESTGRID_URL/v1/types/rating -d '{
"rating" : "explicit"
}'
# Status code: 201
{"message":"Type rating is created with explicit rating."}
Creating a type with the same name causes an error:
$ curl -XPUT $SUGGESTGRID_URL/v1/types/rating
# Status code: 409
{"error_uri":"https://suggestgrid.com/docs/errors#type-already-exists","error_text":"Type Already Exists","error_description":"Type already exists."}
Creating a type with invalid rating type causes an error:
$ curl -XPUT $SUGGESTGRID_URL/v1/types/type -d '{
"rating" : "invalid"
}'
# Status code: 422
{"error_uri":"https://suggestgrid.com/docs/errors#invalid-rating-type","error_text":"Invalid Rating Parameter","error_description":"Rating parameter must be either explicit or implicit."}
Parameters
URI/Query Parameters
Name | Type | Required | Description |
---|
Body Parameters
type_request_body (
object
)
Name | Type | Required | Description |
---|---|---|---|
rating | string | false | The rating type of the type. Could be "explicit" or "implicit", where "implicit" is the default. |
type | string | true | The name of the type. |
Gets Properties of a Type
GET /v1/types/{type}
Returns the options of a type. The response rating parameter.
$ curl -XGET $SUGGESTGRID_URL/v1/types/rating
# Status code: 200
{"rating":"explicit"}
$ curl -XGET $SUGGESTGRID_URL/v1/types/view
# Status code: 200
{"rating":"implicit"}
$ curl -XGET $SUGGESTGRID_URL/v1/types/non_existent
# Status code: 404
{"error_uri":"https://suggestgrid.com/docs/errors#type-is-not-found","error_text":"Type Is Not Found","error_description":"The type in the request is not found."}
Parameters
URI/Query Parameters
Name | Type | Required | Description |
---|---|---|---|
type | string | true | The name of the type to get properties. |
Deletes a Type
DELETE /v1/types/{type}
Warning: Deletes the type with all of its actions and its recommendation model.
$ curl -XDELETE $SUGGESTGRID_URL/v1/types/rating
# Status code: 200
{"message":"Type rating is deleted."}
$ curl -XDELETE $SUGGESTGRID_URL/v1/types/rating
# Status code: 404
{"error_uri":"https://suggestgrid.com/docs/errors#type-is-not-found","error_text":"Type Is Not Found","error_description":"The type in the request is not found."}
Parameters
URI/Query Parameters
Name | Type | Required | Description |
---|---|---|---|
type | string | true | The name of the type to be deleted. |
Gets All Types
GET /v1/types
Returns all type names in an array named types.
$ curl -XGET $SUGGESTGRID_URL/v1/types
# Status code: 200
{"types":["view", "rating"]}
Deletes All Types
DELETE /v1/types
Deletes ALL the types and ALL the actions.
$ curl -XDELETE $SUGGESTGRID_URL/v1/types
# Status code: 200
{"message":"Deleted all types"}
Action Methods
Action methods are for creating, getting, and deleting actions. Refer to actions for an overview.
Posts an Action
POST /v1/actions -d {action}
Posts an action to the given type in the body. The body must have user id, item id and type. Rating is required for actions sent to an explicit type.
$ curl -XPOST $SUGGESTGRID_URL/v1/actions -d '{
"type": "views",
"user_id" : "123",
"item_id" : "456"
}'
# Status code: 201
{"message":"Action posted."}
$ curl -XPOST $SUGGESTGRID_URL/v1/actions -d '{
"type:" : "ratings",
"user_id" : "123",
"item_id" : "456",
"rating" : 3
}'
# Status code: 201
{"message":"Action posted."}
Parameters
Body Parameters
action (
object
)
Name | Type | Required | Description |
---|---|---|---|
item_id | string | true | The item id of the item the action is performed on. |
rating | number | false | The optional rating given by the user, if the type is explicit. |
timestamp | integer | false | The optional UNIX epoch timestamp of the action. Defaults to the current timestamp. |
type | string | true | The type that the action belongs to. |
user_id | string | true | The user id of the performer of the action. |
Posts Actions
POST /v1/actions/_bulk --data-binary @file
Posts bulk actions to SuggestGrid. The recommended method for posting multiple actions at once.
If you're providing text file input to curl, you must use the --data-binary flag instead of -d (or --data). The latter doesn't preserve newlines.
There's a limit of lines, hence number of objects you can send in one requests. That's default to 10000.
Bulk data structure:
{action}\n
{action}\n
{action}\n
{action}\n
{action}\n
An example request for bulk action request is the following:
$ cat actions
{"type": "ratings", "user_id" : "100", "item_id" : "10", "rating" : 2}
{"type": "ratings", "user_id" : "100", "item_id" : "11", "rating" : 3}
{"type": "ratings", "user_id" : "100", "item_id" : "12", "rating" : 5}
{"type": "ratings", "user_id" : "100", "item_id" : "13", "rating" : 2}
{"type": "ratings", "user_id" : "100", "item_id" : "14", "rating" : 3}
{"type": "ratings", "user_id" : "100", "item_id" : "15", "rating" : 3}
{"type": "ratings", "user_id" : "101", "item_id" : "16", "rating" : 5}
{"type": "ratings", "user_id" : "101", "item_id" : "17", "rating" : 4}
{"type": "ratings", "user_id" : "101", "item_id" : "18", "rating" : 5}
{"type": "ratings", "user_id" : "101", "item_id" : "99", "rating" : 5}
$ curl -XPOST $SUGGESTGRID_URL/v1/actions/_bulk --data-binary @actions
# Status code: 201
{"message":"Bulk action post is successful.","errors":[]}
Parameters
Gets Actions
GET /v1/actions ( type | user_id | item_id | older_than | size | from )
Get actions. Defaut responses will be paged by 10 actios each. Type, user id, item id, or older than parameters could be provided. The intersection of the provided parameters will be returned.
If no query parameters is provided, all the actions will be returned:
$ curl -XGET $SUGGESTGRID_URL/v1/actions
# Status code: 200
{"actions":[{"type":"default_type","timestamp":1490128243,"user_id":"325","item_id":"168","rating":3},{"type":"default_type","timestamp":1490182264,"user_id":"713","item_id":"448","rating":2},{"type":"default_type","timestamp":1490182264,"user_id":"230","item_id":"969","rating":4},{"type":"default_type","timestamp":1490182382,"user_id":"276","item_id":"234","rating":5},{"type":"default_type","timestamp":1490185267,"user_id":"154","item_id":"754","rating":5},{"type":"default_type","timestamp":1490186234,"user_id":"328","item_id":"918","rating":4},{"type":"default_type","timestamp":1490182623,"user_id":"128","item_id":"588","rating":5},{"type":"default_type","timestamp":1490182128,"user_id":"950","item_id":"101","rating":4},{"type":"default_type","timestamp":1490182551,"user_id":"324","item_id":"298","rating":5},{"type":"default_type","timestamp":1490182512,"user_id":"232","item_id":"315","rating":5}],"count":10,"total_count":10}
You can include any of type
, user_id
, item_id
, and older_than
query parameters and SuggestGrid would return the actions satisfying all the query parameters:
older_than
value could be a ISO 8601 duration, or a Unix time number.
$ curl -XGET $SUGGESTGRID_URL/v1/actions?user_id=325&item_id=168
# Status code: 200
{"actions":[{"type":"default_type","timestamp":1490128243,"user_id":"325","item_id":"168","rating":3}],"count":1,"total_count":1}
You can also include from
and size
query parameters to nativage throught the reponse actions. From defaults to 0 and size defaults to 10. Returned actions are sorted from the most recent one to the least recent ones.
Parameters
URI/Query Parameters
Name | Type | Required | Description |
---|---|---|---|
from | integer | The number of users to be skipped from the response. Defaults to 0. Must be bigger than or equal to 0. This parameter must be string represetation of an integer like "1". | |
item_id | string | Get actions of an item id. | |
older_than | string | Get actions older than the given duration, or the given time number. Could be a ISO 8601 duration, or a Unix time number. Specifications are available at https://en.wikipedia.org/wiki/ISO_8601#Durations, or https://en.wikipedia.org/wiki/Unix_time. | |
size | integer | The number of the users response. Defaults to 10. Must be between 1 and 10,000 inclusive. This parameter must be string represetation of an integer like "1". | |
type | string | Get actions of a type. | |
user_id | string | Get actions of a user id. |
Delete Actions
DELETE /v1/actions ( type | user_id | item_id | older_than )
Warning: Please use get actions with the exact parameters first to inspect the actions to be deleted.
- Type must be provided.
- If user id is provided, all actions of the user will be deleted.
- If item id is provided, all actions on the item will be deleted.
- If older than is provided, all actions older than the timestamp or the duration will be deleted.
- If a number of these parameters are provided, the intersection of these parameters will be deleted.
- In addition to a type, at least one of these parameters must be provided. In order to delete all the actions of a type, delete the type.
Type and at least one more parameter must be provided for all delete actions queries.
Delete a user's actions:
DELETE /v1/actions?type={type}&user_id={user_id}
$ curl -XDELETE $SUGGESTGRID_URL/v1/actions?type=ratings&user_id=1
# Status code: 200
{"message":"Delete actions query accepted."}
Delete an item's actions:
DELETE /v1/actions?type={type}&item_id={item_id}
$ curl -XDELETE $SUGGESTGRID_URL/v1/actions?type=ratings&item_id=10
# Status code: 200
{"message":"Delete actions query accepted."}
Delete old actions:
older_than
value could be a ISO 8601 duration in the form of PnDTnHnM, or a Unix time number.
Example durations:
P365D
: Approximately a year.P30D
: Approximately a month.P1DT12H
: One and a half days.P1D
: A day (where a day is 24 hours or 86400 seconds).PT12H
: 10 hours (where an hour is 3600 seconds).PT1M
: 1 minute.
Delete actions older than a month:
$ curl -XDELETE $SUGGESTGRID_URL/v1/actions?type=ratings&older_than=P30D
# Status code: 200
{"message":"Delete actions query accepted."}
Delete actions by query:
DELETE /v1/actions?type={type}&(user_id={user_id}&item_id={item_id}&older_than={timestamp_or_duration}
You can include any of user_id
, item_id
, and older_than
parameters to the delete query and SuggestGrid would delete the intersection of the given queries accordingly.
For example, if all of user_id
, item_id
, and older_than
are provided, SuggestGrid would delete the actions of the given user on the given item older than the given time or duration.
$ curl -XDELETE $SUGGESTGRID_URL/v1/actions?type=ratings&user_id=1&item_id=30&older_than=891628467
# Status code: 200
{"message":"Delete actions query accepted."}
It's highly recommended to first get the actions with the same parameters before deleting actions.
Parameters
URI/Query Parameters
Name | Type | Required | Description |
---|---|---|---|
item_id | string | Delete actions of an item id. | |
older_than | string | Delete actions older than the given duration, or the given time number. Could be a ISO 8601 duration, or a Unix time number. Specifications are available at https://en.wikipedia.org/wiki/ISO_8601#Durations, or https://en.wikipedia.org/wiki/Unix_time. | |
type | string | true | Delete actions of a type. This parameter and at least one other parameter is required. |
user_id | string | Delete actions of a user id. |
Metadata Methods
Metadata methods are for creating, getting, and deleting user, and item metadata. Refer to metadata for an overview.
Posts a User
POST /v1/users + {metadata}
Posts a user metadata. Note that this operation completely overrides previous metadata for the id, if it exists.
$ curl -XPOST $SUGGESTGRID_URL/v1/users -d '{
"id" : "123",
"name" : "John Doe"
}'
# Status code: 201
{"message":"Created a user metadata."}
Invalid request:
$ curl -XPOST $SUGGESTGRID_URL/v1/users
# Status code: 400
{"error_uri":"https://suggestgrid.com/docs/errors#body-is-missing","error_text":"Required Request Body Is Missing","error_description":"Body is missing from the request."}
Invalid body (objects are not allowed for properties):
$ curl -XPOST $SUGGESTGRID_URL/v1/users -d '{
"id" : "123",
"name" : "John Doe",
"properties": {"gender": "male"}
}'
# Status code: 400
{"error_uri":"https://suggestgrid.com/docs/errors#metadata-is-invalid","error_text":"Metadata Is Invalid","error_description":"Metadata is invalid:","error_details":"boolean?, and string?, and number?, and nil?, and vector?, and vector?, and vector?, and vector? validations are failed."}
Parameters
Body Parameters
metadata (
object
)
Name | Type | Required | Description |
---|---|---|---|
id | string | true | The id of the metadata of a user or an item. |
Posts Users
POST /v1/users/_bulk --data-binary @file
Posts user metadata in bulk. Note that this operation completely overrides metadata with the same ids, if they exist.
If you're providing text file input to curl, you must use the --data-binary flag instead of -d (or --data). The latter doesn't preserve newlines.
There's a limit of lines, hence number of objects you can send in one requests. That's default to 10000.
Bulk data structure:
{user}\n
{user}\n
{user}\n
{user}\n
{user}\n
An example request for bulk user post request is the following:
$ cat users
{"id": 9394182, "age": 28, "name": "Carr Ortega"}
{"id": 6006895, "age": 29, "name": "Avis Horton"}
{"id": 6540497, "age": 29, "name": "Jami Bishop"}
{"id": 9801076, "age": 26, "name": "Bauer Case"}
{"id": 1967970, "age": 26, "name": "Rosetta Cole"}
{"id": 6084106, "age": 20, "name": "Burris Knowles"}
{"id": 4815289, "age": 21, "name": "Simon Daugherty"}
{"id": 7034179, "age": 24, "name": "Shaw Simon"}
{"id": 2079449, "age": 35, "name": "Serena Bates"}
{"id": 6191531, "age": 21, "name": "Sabrina Grant"}
$ curl -XPOST $SUGGESTGRID_URL/v1/users/_bulk --data-binary @users
# Status code: 201
{"message":"Bulk user metadata upload is successful.","errors":[]}
An invalid request is the following:
$ cat users
{"id": 9394182, "age": 28, "name": "Carr Ortega"}
{"id": 6006895, "age": 29, "name": "Avis Horton"}
{"id": 6540497, "age": 29, "name": "Jami Bishop"}
{"id": 9801076, "age": 26, "name": "Bauer Case"}
{"id": 1967970, "age": 26, "name": "Rosetta Cole"}
{"id": 6084106, "age": 20, "name": "Burris Knowles"}
{"id": 4815289, "age": 21, "name": "Simon Daugherty"}
{"id": 7034179, "age": 24, "name": "Shaw Simon"}
{"name": "Serena Bates"}
{"id": 6191531, "age": 21, "name": "Sabrina Grant", "param": {"key": "value"}}
$ curl -XPOST $SUGGESTGRID_URL/v1/users/_bulk --data-binary @users
# Status code: 201
{"message":"Some metadata is not uploaded successfully.","errors":[{"message":"Metadata is invalid","value":{"name":"Serena Bates"}"error":{"id":"missing-required-key"}}{"message":"Metadata is invalid","value":{"id":6191531,"age":21,"name":"Sabrina Grant","param":{"key":"value"}}"error":{"param":["not",["matches-some-precondition?",{"key":"value"}]]}}]}
Parameters
Gets A User
GET /v1/users/{user_id}
Returns a user metadata if it exists.
$ curl -XGET $SUGGESTGRID_URL/v1/users/123
# Status code: 200
{"id": "123", "name": "John Doe"}
Parameters
URI/Query Parameters
Name | Type | Required | Description |
---|---|---|---|
user_id | string | true | The user id to get its metadata. |
Gets Users
GET /v1/users ( size | from )
Get items and total count of items. Page and per-page parameters could be set.
$ curl -XGET $SUGGESTGRID_URL/v1/users
# Status code: 200
{"users":[{"id":"123","name":"John Doe"}],"count":1,"total_count":1}
Parameters
URI/Query Parameters
Name | Type | Required | Description |
---|---|---|---|
from | integer | The number of users to be skipped from the response. Defaults to 0. Must be bigger than or equal to 0. This parameter must be string represetation of an integer like "1". | |
size | integer | The number of the users response. Defaults to 10. Must be between 1 and 10,000 inclusive. This parameter must be string represetation of an integer like "1". |
Deletes a User
DELETE /v1/users/{user_id}
Deletes a user metadata with the given user id.
$ curl -XDELETE $SUGGESTGRID_URL/v1/users/123
# Status code: 200
{"message":"Deleted a user metadata."}
Parameters
URI/Query Parameters
Name | Type | Required | Description |
---|---|---|---|
user_id | string | true | The user id to delete its metadata. |
Deletes All Users
DELETE /v1/users
Warning: Deletes all user metadata from SuggestGrid.
$ curl -XDELETE $SUGGESTGRID_URL/v1/users
# Status code: 200
{"message":"Deleted all user metadata."}
Posts An Item
POST /v1/items + {metadata}
Posts an item metadata. Note that this operation completely overrides previous metadata for the id, if it exists.
$ curl -XPOST $SUGGESTGRID_URL/v1/items -d '{
"id" : "10",
"manufacturer" : "Apple"
}'
# Status code: 201
{"message":"Created an item metadata."}
Invalid request:
curl -XPOST https://sys:key@localhost:9090/v1/items
# Status code: 400
{"error_uri":"https://suggestgrid.com/docs/errors#body-is-missing","error_text":"Required Request Body Is Missing","error_description":"Body is missing from the request."}
Unsupported data type:
$ curl -XPOST $SUGGESTGRID_URL/v1/items -d '{
"id" : "123",
"manufacturer" : "Apple",
"properties": {"price": 1000}
}'
# Status code: 400
{"error_uri":"https://suggestgrid.com/docs/errors#metadata-is-invalid","error_text":"Metadata Is Invalid","error_description":"Metadata is invalid:","error_details":"boolean?, and string?, and number?, and nil?, and vector?, and vector?, and vector?, and vector? validations are failed."}
Parameters
Body Parameters
metadata (
object
)
Name | Type | Required | Description |
---|---|---|---|
id | string | true | The id of the metadata of a user or an item. |
Posts Items
POST /v1/items/_bulk --data-binary @file
Posts item metadata in bulk. Note that this operation completely overrides metadata with the same ids, if they exist.
If you're providing text file input to curl, you must use the --data-binary flag instead of -d (or --data). The latter doesn't preserve newlines.
There's a limit of lines, hence number of objects you can send in one requests. That's default to 10000.
Bulk data structure:
{item}\n
{item}\n
{item}\n
{item}\n
{item}\n
An example request for bulk item post request is the following:
$ cat items
{"id": "25922342", "manufacturer": "Vicon", "price": 348}
{"id": "80885987", "manufacturer": "Aquamate", "price": 771}
{"id": "66865570", "manufacturer": "Ovolo", "price": 347}
{"id": "40386676", "manufacturer": "Dogspa", "price": 103}
{"id": "71746854", "manufacturer": "Exoplode", "price": 310}
{"id": "53538832", "manufacturer": "Teraprene", "price": 832}
{"id": "15123861", "manufacturer": "Comtext", "price": 548}
{"id": "72006635", "manufacturer": "Ohmnet", "price": 340}
{"id": "44591300", "manufacturer": "Ronelon", "price": 93}
{"id": "43275286", "manufacturer": "Comtest", "price": 608}
$ curl -XPOST $SUGGESTGRID_URL/v1/items/_bulk --data-binary @items
# Status code: 201
{"message":"Bulk user metadata upload is successful.","errors":[]}
An invalid request is the following:
$ cat items
{"manufacturer": "Vicon", "price": 348}
{"id": "80885987", "manufacturer": "Aquamate", "price": 771}
{"id": "66865570", "manufacturer": "Ovolo", "price": 347}
{"id": "40386676", "manufacturer": "Dogspa", "price": 103}
{"id": "71746854", "manufacturer": "Exoplode", "price": 310}
{"id": "53538832", "manufacturer": "Teraprene", "price": 832}
{"id": "15123861", "manufacturer": "Comtext", "price": 548}
{"id": "72006635", "manufacturer": "Ohmnet", "price": 340}
{"id": "44591300", "manufacturer": "Ronelon", "price": 93}
{"id": "43275286", "manufacturer": "Comtest", "price": 608}
$ curl -XPOST $SUGGESTGRID_URL/v1/items/_bulk --data-binary @items
# Status code: 201
{"message":"Some metadata is not uploaded successfully.","errors":[{"message":"Metadata is invalid","value":{"manufacturer":"Vicon","price":348}"error":{"id":"missing-required-key"}}]}
Parameters
Gets An Item
GET /v1/items/{item_id}
Returns an item metadata if it exists.
$ curl -XGET $SUGGESTGRID_URL/v1/items/10
# Status code: 200
{"id":"10", "manufacturer": "Apple"}
Parameters
URI/Query Parameters
Name | Type | Required | Description |
---|---|---|---|
item_id | string | true | The item id to get its metadata. |
Gets Items
GET /v1/items ( size | from )
Gets items and total count of items. Page and per-page parameters could be set.
$ curl -XGET $SUGGESTGRID_URL/v1/items
# Status code: 200
{"items":[{"id":"10", "manufacturer": "Apple"}],"count":1,"total_count":1}
Parameters
URI/Query Parameters
Name | Type | Required | Description |
---|---|---|---|
from | integer | The number of users to be skipped from the response. Defaults to 0. Must be bigger than or equal to 0. This parameter must be string represetation of an integer like "1". | |
size | integer | The number of the users response. Defaults to 10. Must be between 1 and 10,000 inclusive. This parameter must be string represetation of an integer like "1". |
Delete An Item
DELETE /v1/items/{item_id}
Deletes an item metadata with the given item id.
$ curl -XDELETE $SUGGESTGRID_URL/v1/items/10
# Status code: 200
{"message":"Deleted an item metadata."}
Parameters
URI/Query Parameters
Name | Type | Required | Description |
---|---|---|---|
item_id | string | true | The item id to delete its metadata. |
Deletes All Items
DELETE /v1/items
Warning: Deletes all item metadata from SuggestGrid.
$ curl -XDELETE $SUGGESTGRID_URL/v1/items
# Status code: 200
{"message":"Deleted all item metadata."}
Recommendation Methods
Recommendation methods are for getting recommended items for users, or recommended users for items. Refer to recommendations for an overview.
Gets Recommended Users
POST /v1/recommend/users -d {query}
Returns recommended users for the query.
examples:
$ curl -XPOST $SUGGESTGRID_URL/v1/recommend/users -d '{
"type" : "type",
"item_id" : "42"
}'
# Status code: 200
{"users":[{"id":"131"},{"id":"13"},{"id":"14"},{"id":"34"},{"id":"51"},{"id":"11"},{"id":"23"},{"id":"54"},{"id":"62"},{"id":"29"}],"count":10,"total_count":5512}
$ curl -XPOST $SUGGESTGRID_URL/v1/recommend/users -d '{
"type" : "type",
"item_ids" : ["42", "532", "841"]
}'
# Status code: 200
{"users":[{"id":"1"},{"id":"84"},{"id":"9"},{"id":"32"},{"id":"45"}],"count":5,"total_count":5}
$ curl -XPOST $SUGGESTGRID_URL/v1/recommend/users -d '{
"type" : "type",
"item_ids" : ["42", "532", "841"],
"similar_user_id" : "100",
"except" : ["100"],
"size" : 5
}'
# Status code: 200
{"users":[{"id":"1"},{"id":"84"},{"id":"9"},{"id":"32"},{"id":"45"}],"count":5,"total_count":5412}
$ curl -XPOST $SUGGESTGRID_URL/v1/recommend/users -d '{
"type" : "type",
"item_id" : "42",
"size" : 100,
"fields" : ["name"],
"filter" : {
"less_equal" : {
"age" : 60
}
}
}'
# Status code: 200
{"users":[{"id":"11","name":"Robert"},{"id":"848","name":"Mike"},{"id":"2","name":"Jennifer"}],"count":3,"total_count":3}
You can read filters and fields documentations for further reference.
Parameters
Body Parameters
get_recommended_users_body (
object
)
Name | Type | Required | Description |
---|---|---|---|
except | array | false | These user ids that will not be included in the response. |
fields | array | false | The metadata fields to be included in returned user objects. |
filter | false | ||
from | integer | false | The number of most recommended items to be skipped from the response. Defaults to 0. |
item_id | string | false | The item id of the query. |
item_ids | array | false | The item ids of the query. Exactly one of item id or item ids parameters must be provided. |
similaruserid | string | false | Similar user that the response should be similar to. |
similaruserids | array | false | Similar users that the response should be similar to. At most one of similar user and similar users parameters can be provided. |
size | integer | false | The number of users requested. Defaults to 10. Must be between 1 and 10,000 inclusive. |
type | string | false | The type of the query. Recommendations will be calculated based on actions of this type. |
types | array | false | The types of the query. Exactly one of type or types parameters must be provided. |
Gets Recommended Items
POST /v1/recommend/items -d {query}
Returns recommended items for the query.
examples:
$ curl -XPOST $SUGGESTGRID_URL/v1/recommend/items -d '{
"type" : "type",
"user_id" : "42"
}'
# Status code: 200
{"items":[{"id":"451"},{"id":"456"}],"count":2,"total_count":2}
$ curl -XPOST $SUGGESTGRID_URL/v1/recommend/items -d '{
"type" : "type",
"user_ids" : ["42", "532", "841"]
}'
# Status code: 200
{"items":[{"id":"121"},{"id":"33"},{"id":"12"},{"id":"32"},{"id":"49"},{"id":"11"},{"id":"23"},{"id":"54"},{"id":"62"},{"id":"29"}],"count":10,"total_count":4123}
$ curl -XPOST $SUGGESTGRID_URL/v1/recommend/items -d '{
"type" : "type",
"user_ids" : ["42", "532", "841"],
"similar_item_id" : "321",
"size" : 3
}'
# Status code: 200
{"items":[{"id":"13"},{"id":"65"},{"id":"102"}],"count":3,"total_count":3}
$ curl -XPOST $SUGGESTGRID_URL/v1/recommend/items -d '{
"type" : "type",
"user_id" : "42",
"size" : 5,
"filter" : {
"less_equal" : {
"price" : 100
}
}
}'
# Status code: 200
{"items":[{"id":"930"},{"id":"848"},{"id":"102"},{"id":"303"},{"id":"593"}],"count":5,"total_count":51351}
$ curl -XPOST $SUGGESTGRID_URL/v1/recommend/items -d '{
"type" : "type",
"user_id" : "42",
"fields" : ["category"],
"filter" : {
"exact" : {
"manufacturer" : "Apple"
}
}
}'
# Status code: 200
{"items":[{"id":"930","category":"notebook"},{"id":"848","category":"keyboard"},{"id":"102","category":"watch"}],"count":3,"total_count":3}
You can read filters and fields documentations for further reference.
Parameters
Body Parameters
get_recommended_items_body (
object
)
Name | Type | Required | Description |
---|---|---|---|
except | array | false | These item ids that will not be included in the response. |
fields | array | false | The metadata fields to be included in returned item objects. |
filter | false | ||
from | integer | false | The number of most recommended items to be skipped from the response. Defaults to 0. |
similaritemid | string | false | Similar item that the response should be similar to. |
similaritemids | array | false | Similar items that the response should be similar to. At most one of similar item and similar items parameters can be provided. |
size | integer | false | The number of items requested. Defaults to 10. Must be between 1 and 10,000 inclusive. |
type | string | false | The type of the query. Recommendations will be calculated based on actions of this type. |
types | array | false | The types of the query. Exactly one of type or types parameters must be provided. |
user_id | string | false | The user id of the query. |
user_ids | array | false | The user ids of the query. Exactly one of user id or user ids parameters must be provided. |
Similarity Methods
Similarity methods are for getting similar items, or similar users. Refer to similarities for an overview.
Gets Similar Users
POST /v1/similar/users -d {query}
Returns similar users for the query.
$ curl -XPOST $SUGGESTGRID_URL/v1/similar/users -d '{
"type": "views",
"user_id": "1"
}'
# Status code: 200
{"users":[{"id":"12"},{"id":"432"},{"id":"133"}],"count":3,"total_count":3}
$ curl -XPOST $SUGGESTGRID_URL/v1/similar/users -d '{
"type": "views",
"user_id": "1",
"except": ["12"]
}'
# Status code: 200
{"users":[{"id":"432"},{"id":"133"}],"count":2,"total_count":2}
$ curl -XPOST $SUGGESTGRID_URL/v1/similar/users -d '{
"type": "views",
"user_ids" : ["42", "532", "841"],
"size": 3,
"except": 3,
"fields": ["name"],
"filter" : {
"less_equal" : {
"age" : 20
}
}
}'
# Status code: 200
{"users":[{"id":"400","name":"Jason"},{"id":"132","name":"Scarlett"},{"id":"503","name":"Amy"}],"count":3,"total_count":3}
You can read filters and fields documentations for further reference.
Parameters
Body Parameters
get_similar_users_body (
object
)
Name | Type | Required | Description |
---|---|---|---|
except | array | false | These user ids that will not be included in the response. |
fields | array | false | The metadata fields to be included in returned user objects. |
filter | false | ||
from | integer | false | The number of most similar users to be skipped from the response. Defaults to 0. |
size | integer | false | The number of users requested. Defaults to 10. Must be between 1 and 10,000 inclusive. |
type | string | false | The type of the query. Similarities will be calculated based on actions of this type. |
types | array | false | The types of the query. Exactly one of type or types parameters must be provided. |
user_id | string | false | The user id of the query. |
user_ids | array | false | The user ids of the query. Exactly one of user id or user ids parameters must be provided. |
Gets Similar Items
POST /v1/similar/items -d {query}
Returns similar items for the query.
examples:
$ curl -XPOST $SUGGESTGRID_URL/v1/similar/items -d '{
"type": "views",
"item_id": "1"
}'
# Status code: 200
{"items":[{"id":"12"},{"id":"451"},{"id":"456"}],"count":3,"total_count":3}
$ curl -XPOST $SUGGESTGRID_URL/v1/similar/items -d '{
"type": "views",
"item_id": "1",
"except": ["12"]
}'
# Status code: 200
{"items":[{"id":"451"},{"id":"456"}],"count":3,"total_count":3}
$ curl -XPOST $SUGGESTGRID_URL/v1/similar/items -d '{
"type": "views",
"item_ids": ["3","5","8"],
"size": 3,
"except": 3,
"fields": ["category"],
"filter" : {
"less_equal" : {
"capacity" : 20
}
}
}'
# Status code: 200
{"items":[{"id":"451","category":"television"},{"id":"656","category":"blu-ray-dvd-players"}],"count":2,"total_count":2}
You can read filters and fields documentations for further reference.
Parameters
Body Parameters
get_similar_items_body (
object
)
Name | Type | Required | Description |
---|---|---|---|
except | array | false | These item ids that will not be included in the response. |
fields | array | false | The metadata fields to be included in returned item objects. |
filter | false | ||
from | integer | false | The number of most similar items to be skipped from the response. Defaults to 0. |
item_id | string | false | The item id of the query. Get similar items to given item id. Either item id or item ids must be provided. |
item_ids | array | false | The item ids of the query. Exactly one of item id or item ids parameters must be provided. Get similar items to given item ids. Either item id or item ids must be provided. |
size | integer | false | The number of items requested. Defaults to 10. Must be between 1 and 10,000 inclusive. |
type | string | false | The type of the query. Similarities will be calculated based on actions of this type. |
types | array | false | The types of the query. Exactly one of type or types parameters must be provided. |