# US Map Retail Evidence API

> US Map Retail Evidence API is a paid API for AI agents from api.timzinin.com, paid per call via x402, $0.08/call, status unknown (last checked 2026-10-31).

Retrieves retail evidence and product data mapped to US retail locations, accepting product identifiers and returning structured retail presence information

## Facts

- Endpoint: POST https://api.timzinin.com/api/us-map-retail-evidence?utm_source=zero.xyz
- Price: $0.08/call
- Payment: x402
- Status: unknown
- Last checked: 2026-10-31
- Activations on Zero: 0
- Tags: x402
- Canonical page: https://www.zero.xyz/c/us-map-retail-evidence-api-94d3f397
- Structured record (JSON): https://api.zero.xyz/v1/capabilities/cap_zeig2K3cQR3oezhawAbAe

Status and success rate cover calls made through Zero and Zero's own probes. Third-party monitors may report differently.

## How to call it through Zero

Zero handles the 402 payment challenge and records the run. With the Zero CLI installed (`npm i -g @zeroxyz/cli`):

```sh
zero fetch --capability us-map-retail-evidence-api-94d3f397 -d '<json body>'
```

Example prompt: Pull US retail evidence for these 5 products — UPC:012345678901, ASIN:B08N5WRWNW, usItemId:123456789, TCIN:87654321, and productId:abc123 — using dataset ID 'cpg-q2-2024' and mark the dataset as closed with 5 expected items.

## When to prefer this

Choose this endpoint when you need structured retail evidence for specific US retail locations tied to product identifiers like UPCs, ASINs, Walmart item IDs, or Target TCINs. It is ideal for CPG brands, market researchers, and e-commerce analysts who need pay-per-call, on-demand retail presence data without a subscription. Prefer this over general web scraping or third-party syndicated data services when you need programmatic, per-product retail evidence at low cost ($0.08/call).

## Known failure modes

- Invalid product identifier format (must match productId|upc|asin|usItemId|tcin pattern) returns validation error
- Exceeding 100 rows or 100 watchUniverse items returns a schema validation error
- Missing required schemaVersion '1.0' causes request rejection
- Empty rows array (minItems:1 not met) causes a bad request error
- Payment failure or insufficient USDC balance returns HTTP 402
- Unknown or malformed datasetId pattern causes rejection

## How this service works

Pay-per-call data & tool APIs

## Output

Returns structured retail evidence records for each submitted product identifier, indicating retail presence, availability, and location data across US retail channels such as Walmart, Target, and Amazon. The response is organized per row/product input.

## Request schema (JSON Schema)

```json
{
 "type": "object",
 "properties": {
  "rows": {
   "type": "array",
   "items": {
    "$ref": "#/definitions/row"
   },
   "maxItems": 100,
   "minItems": 1
  },
  "options": {
   "$ref": "#/definitions/options"
  },
  "watchId": {
   "$ref": "#/definitions/bazaarShared0"
  },
  "datasetId": {
   "type": "string",
   "pattern": "^[A-Za-z0-9][A-Za-z0-9_-]{0,99}$"
  },
  "requestId": {
   "$ref": "#/definitions/bazaarShared0"
  },
  "schemaVersion": {
   "const": "1.0"
  },
  "watchUniverse": {
   "type": "array",
   "items": {
    "type": "string",
    "pattern": "^(productId|upc|asin|usItemId|tcin):.+$"
   },
   "maxItems": 100,
   "minItems": 1
  },
  "datasetCoverage": {
   "type": "object",
   "required": [
    "closed",
    "expectedItems"
   ],
   "properties": {
    "closed": {
     "const": true
    },
    "expectedItems": {
     "type": "integer",
     "maximum": 100,
     "minimum": 0
    }
   },
   "additionalProperties": false
  },
  "openrouterApiKey": {
   "type": "string",
   "minLength": 1
  }
 }
}
```

## More

- Live health (JSON, refreshed every minute): https://www.zero.xyz/c/us-map-retail-evidence-api-94d3f397/health.json
- [Zero catalog index](https://www.zero.xyz/llms.txt)
- [Other services from api.timzinin.com](https://www.zero.xyz/host/api.timzinin.com/llms.txt)