Text Search
This page describes the Text Search API functionality for finding images using text queries. With this service, you can search through your collection of images using natural language descriptions. The API follows the general rules of Ximilar API as described in the First Steps section.
How It Works
The Text Search service works through the following process:
-
Create a Collection: First, create a collection (database of your images) via app.ximilar.com. Different collection types are available for various use cases.
-
Upload Images: Insert your images into the collection using the API. You can upload images via URL or base64 data. We recommend to use URL instead of Base64 data because you will be able to visualize the results.
-
Search with Text: Once your collection is populated, you can search for images using natural language text queries.
Endpoints
Services have different api endpoints for text search, based on collection types/service:
https://api.ximilar.com/similarity/text/photo/v2/text (Photo Similarity)
https://api.ximilar.com/similarity/text/products/v2/text (Product Similarity)
https://api.ximilar.com/similarity/text/fashion/v2/text (Fashion Search)
https://api.ximilar.com/similarity/text/homedecor/v2/text (Home Decor Search)
Text Search
Find images that match a given text query from the collection.
Required attributes
- Name
collection-id- Type
- string
- Description
Your collection ID in the header
- Name
Authorization- Type
- string
- Description
Your API token in the format:
Token YOUR_API_TOKEN
Request parameters
- Name
query_record- Type
- object
- Description
Record containing the text query to search by
- Name
query_record._text_data- Type
- string
- Description
The text query to search for images
- Name
k- Type
- number
- Description
Number of records to be returned, default: 30
- Name
from- Type
- number
- Description
The number of records to be skipped, defaults to 0
- Name
fields_to_return- Type
- array
- Description
Fields to be returned in every record, defaults to ["_id"]
- Name
filter- Type
- object
- Description
Search will be applied only to records satisfying this filter
Response fields
- Name
query_records- Type
- array
- Description
The query record(s) copied from the request
- Name
answer_records- Type
- array
- Description
Records found matching the text query
- Name
answer_count- Type
- number
- Description
Number of returned records
- Name
answer_distances- Type
- array
- Description
Distances between query and individual records in answer_records
Request
curl 'https://api.ximilar.com/similarity/text/fashion/v2/text' -i -X POST \
-H 'Content-Type: application/json;charset=UTF-8' \
-H 'collection-id: __COLLECTION_ID__' \
-H 'Authorization: Token __API_TOKEN__' \
-d '{
"from": 0,
"k": 10,
"query_record": {
"_text_data": "a yellow nike footwear"
},
"fields_to_return": ["_id", "_url"]
}'
Response
{
"status": {
"code": 200,
"text": "OK"
},
"statistics": {
"OperationTime": 150
},
"answer_records": [
{
"_id": "1",
"_url": "https://example.com/image1.jpg"
},
{
"_id": "2",
"_url": "https://example.com/image2.jpg"
}
],
"answer_distances": [0.45, 0.52],
"query_records": [
{
"_text_data": "a modern living room with white furniture and large windows"
}
],
"answer_count": 2
}