Look up products by identifier

Find what published sources say about a product from its GTIN, EAN, UPC, ISBN, ASIN, part number, stock code or page address. Every fact comes back with the source that states it, how sure the match is, and any disagreement between sources. Send one product or a batch of up to 500. Sources are your own catalogue, your connected Amazon store, the Open Food Facts database, a product page you point at, and a web search. Only a web search is charged, and an answer already found is served from cache at no cost. Add enrich to also write content from what was found. Small requests answer inline (200, or 207 when an item failed); larger ones return a job (202). Requires the enrichment:write scope.

Authorization

AuthorizationBearer <token>

API key in the Authorization header: Authorization: Bearer ace_live_.... Use an ace_test_... key for the free, rate-capped sandbox.

In: header

Header Parameters

Idempotency-Key?string

Makes a retried batch return the same job instead of a second one.

Lengthlength <= 255

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Send either one product (q, identifiers, hints, ref, product) or items. Unknown keys are refused.

ref?string

q?string

identifiers?

What you know about the product. Send any that you have. Barcodes are checked against their check digit, and every written form of one number (UPC, EAN, GTIN-14) is treated as the same product.

hints?

market?string

Default for every item.

locale?string

Default for every item.

items?array<>

Items1 <= items <= 500

sources?array<>

Use only these sources. Left out, every available source is used and a web search runs only when the free sources leave the product thin.

Items1 <= items

excludeSources?array<>

fields?array<>

Items1 <= items

freshness?

minConfidence?number

Facts below this are left out of the merged product. They are still listed under facts.

Range0 <= value <= 1

Default0.6

include?array<>

Which sections of each result to return. Default: all.

Items1 <= items

projectId?string

storeId?string

A connected store, for callers who address their project through one.

mode?string

sync accepts at most 10 items.

Value in

"sync"
"async"

dryRun?boolean

Validate the request, say which sources would run for each item and estimate the cost. Nothing is looked up or charged.

product?

What you already hold for this product. Used when writing content with enrich: your fields win over what the lookup found, and it is the only way a price, stock level or rating can reach the copy.

enrich?

Also write content from what was found. The copy is written only from the sourced facts and anything you send in product. Charged like POST /enrichment/content: one unit per product per content type that is written.

Response Body

`application/json`

curl -X POST "https://example.com/enrichment/lookup" \  -H "Content-Type: application/json" \  -d '{    "q": "4006381333931",    "market": "GB"  }'

{  "data": {    "operation": "lookup",    "items": [      {        "index": 0,        "ref": "string",        "status": "ok",        "error": {          "code": "string",          "message": "string",          "details": {}        },        "warnings": [          {            "code": "INVALID_IDENTIFIER",            "field": "string",            "value": "string",            "reason": "empty",            "usedAs": "asin"          }        ],        "match": {          "status": "matched",          "confidence": 0,          "identifiers": {            "property1": "string",            "property2": "string"          },          "partial": true,          "candidates": [            {}          ]        },        "product": {          "title": "string",          "brand": "string",          "description": "string",          "bullets": [            "string"          ],          "category": "string",          "images": [            {              "url": "string",              "source": "string",              "sourceUrl": "string",              "licence": "string",              "attribution": "string"            }          ],          "gtin": "string",          "mpn": "string",          "asin": "string",          "attributes": {            "property1": {              "value": null,              "unit": "string"            },            "property2": {              "value": null,              "unit": "string"            }          }        },        "facts": [          {            "field": "title",            "name": "string",            "value": null,            "unit": "string",            "source": "catalog",            "provider": "open_food_facts",            "url": "http://example.com",            "retrievedAt": "2019-08-24T14:15:22Z",            "matchMethod": "exact_gtin",            "extraction": "structured",            "confidence": 0,            "verified": true,            "licence": "ODbL 1.0",            "attribution": "string"          }        ],        "sources": [          {            "id": "catalog",            "status": "hit",            "reason": "AMAZON_NOT_CONNECTED",            "cached": true,            "stale": true,            "urls": [              "http://example.com"            ],            "attribution": {              "source": "string",              "provider": "string",              "text": "string",              "licence": "string",              "url": "string"            },            "retryAfterMs": 0          }        ],        "conflicts": [          {}        ],        "content": {},        "generation": {          "status": "generated",          "reason": "MATCH_NOT_FOUND",          "units": [            {              "type": "string",              "status": "ok",              "error": {                "code": "string",                "message": "string"              }            }          ],          "skippedContentTypes": [            "string"          ]        },        "usage": {          "searchCalls": 0,          "cacheHits": 0        }      }    ],    "summary": {      "total": 0,      "matched": 0,      "ambiguous": 0,      "notFound": 0,      "errors": 0,      "searchCalls": 0,      "cacheHits": 0,      "generated": 0,      "generationErrors": 0    },    "attributions": [      {        "source": "string",        "provider": "string",        "text": "string",        "licence": "string",        "url": "string"      }    ]  }}

{  "data": {    "id": "string",    "kind": "rules",    "status": "pending",    "progress": {      "phase": "string",      "completed": 0,      "total": 0    },    "estimateMs": 0,    "productCount": 0,    "succeededCount": 0,    "failedCount": 0,    "storeId": "string",    "createdAt": "2019-08-24T14:15:22Z",    "links": {      "self": "string",      "results": "string"    }  }}

{  "data": {    "operation": "lookup",    "items": [      {        "index": 0,        "ref": "string",        "status": "ok",        "error": {          "code": "string",          "message": "string",          "details": {}        },        "warnings": [          {            "code": "INVALID_IDENTIFIER",            "field": "string",            "value": "string",            "reason": "empty",            "usedAs": "asin"          }        ],        "match": {          "status": "matched",          "confidence": 0,          "identifiers": {            "property1": "string",            "property2": "string"          },          "partial": true,          "candidates": [            {}          ]        },        "product": {          "title": "string",          "brand": "string",          "description": "string",          "bullets": [            "string"          ],          "category": "string",          "images": [            {              "url": "string",              "source": "string",              "sourceUrl": "string",              "licence": "string",              "attribution": "string"            }          ],          "gtin": "string",          "mpn": "string",          "asin": "string",          "attributes": {            "property1": {              "value": null,              "unit": "string"            },            "property2": {              "value": null,              "unit": "string"            }          }        },        "facts": [          {            "field": "title",            "name": "string",            "value": null,            "unit": "string",            "source": "catalog",            "provider": "open_food_facts",            "url": "http://example.com",            "retrievedAt": "2019-08-24T14:15:22Z",            "matchMethod": "exact_gtin",            "extraction": "structured",            "confidence": 0,            "verified": true,            "licence": "ODbL 1.0",            "attribution": "string"          }        ],        "sources": [          {            "id": "catalog",            "status": "hit",            "reason": "AMAZON_NOT_CONNECTED",            "cached": true,            "stale": true,            "urls": [              "http://example.com"            ],            "attribution": {              "source": "string",              "provider": "string",              "text": "string",              "licence": "string",              "url": "string"            },            "retryAfterMs": 0          }        ],        "conflicts": [          {}        ],        "content": {},        "generation": {          "status": "generated",          "reason": "MATCH_NOT_FOUND",          "units": [            {              "type": "string",              "status": "ok",              "error": {                "code": "string",                "message": "string"              }            }          ],          "skippedContentTypes": [            "string"          ]        },        "usage": {          "searchCalls": 0,          "cacheHits": 0        }      }    ],    "summary": {      "total": 0,      "matched": 0,      "ambiguous": 0,      "notFound": 0,      "errors": 0,      "searchCalls": 0,      "cacheHits": 0,      "generated": 0,      "generationErrors": 0    },    "attributions": [      {        "source": "string",        "provider": "string",        "text": "string",        "licence": "string",        "url": "string"      }    ]  }}

{  "error": {    "code": "NO_IDENTIFIER",    "message": "Send at least one identifier: a GTIN, EAN, UPC, ISBN, ASIN, part number with a brand, stock code, page address, or a bare value in q."  }}

{  "error": {    "code": "INSUFFICIENT_CREDITS",    "message": "Not enough credits for this request.",    "details": null  }}

{  "error": {    "code": "INSUFFICIENT_CREDITS",    "message": "Not enough credits for this request.",    "details": null  }}

{  "error": {    "code": "PROJECT_SCOPE_MISMATCH",    "message": "This API key is scoped to a different project."  }}

{  "error": {    "code": "INSUFFICIENT_CREDITS",    "message": "Not enough credits for this request.",    "details": null  }}

Look up products by identifier

Authorization

Header Parameters

Request Body

Response Body

200application/json

202application/json

207application/json

400application/json

401application/json

402application/json

403application/json

429application/json

Example noIdentifier

Example invalidIdentifier

Example sourceUnavailable

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`