Documentation

Changelog

06-28-2023

Updated Base URL

The endpoint is now accessible at https://api.reillybuilt.com/functions/v1/recommend.

New Params

budget is now supported as a filter.

Model Improvements

Updated weighted strategies; you’ll notice more distributive scoring amongst products.

Authentication

The Recommendation API uses API keys for authentication.

Your API key is a secret. Do not share it with others or expose it in any client-side code (browsers, apps). Production requests must be routed through your own backend server where your API key can be securely loaded from an environment variable or key management service.

Making Requests

You can paste the command below into your terminal to run your first API request. Make sure to replace $RECOMMEND_API_KEY with your secret API key.

curl https://api.reillybuilt.com/functions/v1/recommend \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $RECOMMEND_API_KEY" \
  -d '{
    "query": "Im interested in board games",
    "limit": 5
    }'

This request queries the recommend service to request 5 product recommendations based on the user-generated query:

I’m interested in board games

You will get a JSON response back that resembles the following:

{
  "id": "a4f2727b-e5dc-49aa-983d-f6fdca97d9c3",
  "created": 1686317379382,
  "data": [
    {
      "product_id": "206229",
      "score": 1
    },
    {
      "product_id": "203697",
      "score": 0.9556
    },
    {
      "product_id": "208257",
      "score": 0.9537
    },
    {
      "product_id": "207471",
      "score": 0.9535
    },
    {
      "product_id": "204090",
      "score": 0.659
    }
  ]
}

Request

To use the API, make a POST request to the /recommend endpoint.

Base URL

The API can be accessed at https://api.reillybuilt.com/functions/v1/recommend.

Note You must use HTTPS. HTTP requests will result in a 301 response to encourage HTTPS.

Headers

Param	Definition
Authorization	This should contain the string Bearer followed by your API key (e.g., `Bearer RECOMMEND_API_KEY`).

Body

Param	Type	Definition
query	String	A string that will be used to generate product recommendations.
product_ids	Array of strings	An array of product IDs used to generate recommendations.
limit	Integer, 1-100	The maximum number of product recommendations you want to receive. This should be a number between 1 and 100.
filters	Object	An object containing filters to apply to the recommendations. Currently, only one filter is supported:
filters.unique_products	Boolean	If true, any products present in the product_ids array will be excluded from the recommendations.
filters.budget	Object	An object containing `min` and `max` keys. Only 1 is required; both can be used.
filters.budget.min	Integer	Apply a min budget threshold for recommendations
filters.budget.max	Integer	Apply a max budget threshold for recommendations

Example

{
  "query": "I'm shopping for massaging items.",
  "product_ids": ["100871"],
  "limit": 20,
  "filters": {
    "budget": {
      "min": 100,
      "max": 250
    },
    "unique_products": true
  }
}

Response

The response will be a JSON object with the following fields:

Param	Definition
id	A unique ID for your request.
created	A timestamp indicating when the request was processed.
data	An array of product recommendations. Each item in the array is an object with two fields:
data.product_id	The ID of the recommended product.
data.score	The score of the recommended product. Higher scores indicate better recommendations.

Status Codes

Code	Meaning
200	Successful request.
400	Bad request. This often means that the request body is missing required fields or the fields have invalid values.
401	Unauthorized. This means the API key provided in the Authorization header is missing or invalid.
405	Method not allowed. This means you’re making a request with an unsupported method. This API only supports POST requests.

Recommend API Docs