Locations

Resolve

Turn one input into a pin. Pass free text, a map URL, lat,lng, a short address, or a mix, plus the country code. You always get JSON: an entry score for whether this is a place, and a match score for the pin.

POST/v1/resolve

Authorizations

Authorizationstringheaderrequired

Bearer token. Use a test key from the dashboard. The header is Authorization: Bearer <token>.

"Bearer trq_test_…"

Body

application/json

inputstringrequired

The thing to locate. Free text (Marina Walk, Dubai), a map URL, coordinates (30.0444, 31.2357), a real Saudi short address (RRMF3275), or a mix. A person name such as Ahmed Ali is refused. A code that only looks like a short address, such as RRRR1111, comes back unresolved with no pin.

"RRMF3275"

countrystringrequired

ISO country code for the place. Required, and it must be a MENA country: SA, AE, KW, QA, BH, OM, EG, JO, MA, LB, IQ, YE, DZ, TN, and the rest of the region. A match in a different country cannot score above 0.4.

"SA"

Response

200 · application/json

input.entry_confidencenumber

0 to 1. How sure we are that the input is a place at all, before any geocoding. A person name stays under 0.3.

"0.94"

input.entry_kindstring

What we found in the input: short_address, address, coordinates, map_url, mixed, or not_a_location.

"short_address"

result.statusstring

resolved when the pin is trustworthy. low_confidence when the best point is weak. not_a_location for a person name. unresolved when nothing real was found, including an unknown short code.

"resolved"

result.coordinatesobject | null

latitude and longitude. Null when the input is not a place or the short code is not real.

result.confidencenumber

0 to 1 match score for the pin. A rooftop or a code Google actually recognizes is high. A hit in the wrong country cannot exceed 0.4.

"0.95"

result.short_addressstring | null

Saudi national short code. A confirmed code from the input, or the nearest national address within 500 meters when the pin is a place that has no code of its own.

"RRMF3275"

result.formatted_addressstring | null

English address line for the pin.

result.localized.arstring | null

Arabic address for the same pin. Omitted when the only Arabic line would be a different building.

Errors

Code	HTTP	When
UNAUTHORIZED	401	Missing or invalid API key or session token.
FORBIDDEN	403	The credential is valid but lacks permission for this action.
INVALID_INPUT	400	The request body failed validation. input and a 2-letter country are required.
COUNTRY_NOT_SUPPORTED	422	Country must be a MENA code such as SA, AE, KW, QA, BH, OM, EG, JO, or MA.
RATE_LIMITED	429	Too many requests for this API key or IP.