Similarity API

The Similarity API is a special API to connect to similarity deployments, where you don’t use a model to make predictions but to find similar data items in your datasets.

The deployment limitations may limit the size and frequency of your requests, and the number of models that you can deploy simultaneously depend on your pricing plan.

Our APIs uses HTTP endpoints to provide an interface between your application and the Platform. This allows you to send requests to specific URLs, including, if needed, examples or data files. Our API then returns standard HTTP codes, and JSON formatted text with the model predictions.

See examples of using the Similarity API in cURL and Python.

Prerequisites

You need to create a Similarity deployment from the deployment view. The deployment view will show you the information you need to use the Deployment API:

OpenAPI specification

In the Deployment view, you will be able to download the API specifications for your model in the standard OpenAPI format.

Structure of a similarity request

To receive similar items from your datasets, you use a HTTP client to send a POST request to the URL indicated on the deployment page that you want to use.

You can send such requests by using cURL, Python (e.g., with the requests package), or our sidekick tool for Python. Other packages, languages, or tools may also be used if they follow the API specifications.

Header

Your request must always have a header containing the deployment token, which is used to authenticate the request.

The header looks like:

Authorization: Basic <token converted to binary 64>

Unlike the Deployment API, the token must be given encoded as a binary 64 string. Check examples in specific languages to see how you can create this string.

Payload

The example for which you want to find similar items is given using multipart form upload.

Such examples can be either an image file or a text. See examples in different languages.

Request a specific number of similar examples

The platform returns by default the 5 most similar examples found in the dataset indexed by the deployment.

In the case of text similarity only, it is possible to specify how many examples should be returned by the platform. You can request more or less than 5 examples to be returned by adding a JSON formatted payload to your request that contains the key limit and the number of examples that you want.

{'limit': 100}

Response

Once you send the request with an example of data you’re looking for, you will receive several examples from your dataset that are the most similar, together with a value of the similarity distance.
You can optionally choose to also return extra features from the similar examples by selecting them in the list of Output features when you create the deployment.

The similar examples are sent as a JSON formatted text string.

  • Text examples are returned directly as text. Here’s an example of the response where 2 similar texts are returned, Text feature is the text data used for similarity calculation, and the deployment returns the extra Output features author and book:

{'deploymentId': '<deployment ID>', 'similarities': [{'distance': 0.1, 'index': 7218, 'features': {'Text feature': 'Never laugh at live dragons.', 'author': 'Tolkien', 'book': 'The Hobbit'}}, {'distance': 0.3, 'index': 841, 'features': {'Text feature': 'Come not between the dragon, and his wrath.', 'author': 'Shakespeare', 'book': 'King Lear'}}]}
  • Image examples are returned as raw file, base 64 encoded strings. Here’s an example of the response where 2 similar images are returned, Image feature is the image data used for similarity calculation, and the deployment returns the extra Output features photographer and year:

{'deploymentId': '<deployment ID>', 'similarities': [{'distance': 0.05, 'index': 1736, 'features': {'Image feature': '/9j/4AAQSkZJRgAB', 'photographer': 'Lovisa Ringborg', 'year': 2021}}, {'distance': 0.12, 'index': 84821, 'features': {'Image feature': 'ZVt+YYbe8BB6Pn+n/aV', 'author': 'Erik Johansson', 'year': 2008}}]}
Was this page helpful?
YesNo