API Endpoints

Collect Event

POST https://api.recomalytics.com/collect?apikey=:apikey

Data ingestion happens in realtime and happens via JSON payloads to this endpoint, new ratings for previously rated user_id, item_id pairs will be overwritten was latest score

Path Parameters

Name	Type	Description
apikey	string	Namespace API key

Request Body

Name	Type	Description
user_id	string	Any arbitrary string which may be used later for generating recommendations
item_id	string	Any arbitrary string which will be returned in calls to other endpoints to identify a unique item
score	number	A floating point number between 0 and 1

204 Event was ingested successfully

Get Similar Items

GET https://api.recomalytics.com/similar?apikey=:apikey&item=:item

This endpoint provides a list of similar items and their similarity score A non-existent item will return no similar items

Query Parameters

Name	Type	Description
apikey	string	Namespace API key
item	string	Item ID to find similar items to

200 Similar items retrieved.

[
  {
    "item_id": "comedy_movie_2",
    "score": 0.6963106238227914
  },
  {
    "item_id": "horror_movie_1",
    "score": 0.4923659639173309
  },
  {
    "item_id": "horror_movie_2",
    "score": 0.27080128015453203
  }
]

Recommend Items

GET https://api.recomalytics.com/recommend?apikey=:apikey&item=:item&user=:user

This endpoint provides personalised recommendations for a specific user, which can be generated from a list of similar items or across all items

Query Parameters

Name	Type	Description
apikey	string	Namespace API key
item	string	Item ID to find similar items to, when excluded recommendations will be across all items
user	string	User ID to base scores on

200

// When no item ID is provided, score is personalised score

[
  {
    "item_id": "comedy_movie_2",
    "score": 0.648262445045573
  },
  {
    "item_id": "horror_movie_1",
    "score": 0.33622238976531893
  },
  {
    "item_id": "horror_movie_2",
    "score": 0.3313009912782784
  }
]

// When item ID is provided, similarity_score is similarity score for that object and the provided item ID

[
  {
    "item_id": "horror_movie_1",
    "similarity_score": 0.23570226039551584,
    "personalised_score": 0.33622238976531893
  },
  {
    "item_id": "comedy_movie_1",
    "similarity_score": 0.6963106238227914,
    "personalised_score": 0.1645161290322581
  }
]