Skip to main content

POST /recognize

Create a request for processing a group of photos.

Uploaded images are processed in batches called scenes, a single report is compiled for all images in the scene. It makes sense to combine in one scene photos of different parts of one shelf or a photo of several shelves of one product category.

Images must be pre-loaded into the system via /uploads or /uploads_by_url.

Adress: POST https://instance_name/api/v1.5/recognize/

Content-type: application/json

Note

The number of requests to the point is limited to 100 requests per minute.

Request body parameters

images list of strings

List of image IDs for processing.

display string (ID)

List of displays ID.

The field is optional, but some report types are not available without the display, e.g. Planogram Compliance and Must Have List.

report_types list of strings

List of reports to be generated.

visit string

Use this field to include images to a previously created visit.

The field is optional. If not specified, a new visit will be created

datetime string (date-time)

The field is optional. If you need to specify the date and time of the visit.

webhook string (url)

Use webhook to reduce latency. If specified, the reports will be sent by POST request to this URL immediately when ready (one by one).

The field is optional. If not specified, the client should explicitly poll reports.

panorama_stack_height number

Hint to panorama stitching engine, see PANORAMA report. Optional.

panorama_stack_width number

Hint to panorama stitching engine, see PANORAMA report. Optional.

counry_code string

Two-character сountry code to specify from which country the sku on the photo eg «RU», «KZ». Standart ISO 3166 (A2). Optional.

retail_chain string

Use retail_chain to define retail chain that owns the shop.

metadata object (dictionary)

Dictionary of additional parameters. Optional.

agent_id string

Agent Client ID . If the agent exists and the name has been changed, it will be updated. The created scene will be associated with this agent.

agent_name string

Agent name. Used to create or update an agent.

Request example

{
  "images": [156673, 156674, 156675, 156676], 
    "display": 13,
    "report_types": [
    "FACING_COUNT", 
    "PLANOGRAM_COMPLIANCE"
  ],
  "country_code": "RU",
  "metadata": {"agent_id": 23, "agent_name": "Paul McCartney"}
}

In response to a successful request, the system issues report IDs. Reports can be accessed later via /reports.

Response example

Response code: 201 (CREATED)

{
  "id": 11234,
  "images": [156673, 156674, 156675, 156676],
  "display": 13,  
  "scene": "4d8b66992cd841f6922723afe9bd8cf8",
  "reports": {
    "FACING_COUNT": 1786,
    "PLANOGRAM_COMPLIANCE": 1789
   }
}

If a webhook is specified, once the reports are generated, JSON will be sent to it with a POST request.

{
  "id": 11234,
  "images": [156673, 156674, 156675, 156676],
  "display": 13,  
  "reports": {
    "1786": {...}, // JSON-текст отчета
    "1786": {...} // JSON-текст отчета
  }
}

Response definitions

id string (ID)

Report ID.

images list of strings

List of image ID's from the request.

display integer

List of display ID's.

reports dictionary report type -> report ID.

Report ID's for the scene.

scene string

Uuid, created scene ID.