Resolve

The Atlas matching ladder, exposed as an endpoint. This is the piece that makes the rest of the platform tolerant of how addresses actually arrive — from lead forms, spreadsheets, storefronts — rather than how you'd wish they arrived.

curl -X POST "https://apis.cloud.feeef.org/v1/geo/resolve" \
  -H "Authorization: Bearer $FEEEF_CLOUD_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "country": "DZ", "state": "بليدة", "city": "beni tamou" }'

{ "data": {
    "stateCode": "09",
    "state": { "name": "Blida" },
    "cityName": "Beni Tamou",
    "city": { "id": "DZ-09-beni-tamou" },
    "confidence": 1.0,
    "method": "exact",
    "autoAccept": true,
    "alternatives": [] } }

Reading method and confidence

method is one of code, exact, phonetic, prefix, skeleton, fuzzy, loose, inferred, best_effort, or unresolved — in roughly descending order of how literally the input matched. It's diagnostic, not something to branch application logic on; the field that actually matters for a decision is autoAccept.

An input that matches ambiguously across states comes back with autoAccept: false and ranked alternatives[] instead of a guess. The right integration pattern:

• autoAccept: true → use stateCode / city.id directly.
• autoAccept: false → either surface alternatives[] to a human (a checkout confirmation step, a support agent's review queue), or reject the order and ask for a cleaner address. Do not default to alternatives[0] silently — that reintroduces the exact problem resolve exists to prevent.

Batch

Up to 500 rows per call. Useful for backfilling a historical order table against the catalog, or validating a CSV import before it becomes shipments.

curl -X POST "https://apis.cloud.feeef.org/v1/geo/resolve/batch" \
  -H "Authorization: Bearer $FEEEF_CLOUD_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "country": "DZ", "rows": [{ "id": "r1", "state": "16", "city": "bab ezouar" }] }'

The response mirrors the input rows in order, matched by the id you sent — billing counts rows, not requests, so a 500-row batch costs the same as 500 individual resolve calls against your geo:resolve quota, but in one round trip instead of 500.