Saudi Address Lookup API
Turn coordinates or a Saudi Short Address (e.g. RCDA6608) into a full, structured national address — district, street, building number, postal code and more — with one HTTPS call.
https://your-hostHTTPS · JSON
X-API-Key header1 credit per successful lookup
Authentication
Every request must carry your secret API key in the X-API-Key header. You can also use Authorization: Bearer <key>.
X-API-Key: sat_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Your key is shown once, when you generate it in the Console → API tab. We store only a hashed version, so we can never show it again. Lost it? Regenerate — the old key stops working instantly. Keys are secret: keep them on your server, never in a mobile app or browser.
The lookup endpoint
/api/v1/lookup
Send a JSON body with an input and an optional language.
| Field | Type | Required | Description |
|---|---|---|---|
| input | string | Yes | Coordinates "24.71,46.67" or a Short Address "RCDA6608". |
| language | string | No | "en" (default) or "ar". |
Input types
Coordinates
Latitude, longitude. "24.7136, 46.6753". Returns the full national address incl. the Short Address.
Short Address
The 8-char Saudi code. "RCDA6608". Resolves to coordinates + full address.
Response
A 200 OK returns the structured address. Fields that can't be resolved are null.
{
"short_address": "RCDA6608",
"formatted": "Al Aqiq, Riyadh 13515, Saudi Arabia",
"building_number": "6608",
"street": "Anas Ibn Malik Road",
"district": "Al Aqiq",
"city": "Riyadh",
"region": "Riyadh",
"postal_code": "13515",
"additional_number": "2745",
"country": "Saudi Arabia",
"lat": 24.7563,
"lng": 46.6295,
"resolved_via": "national_address",
"cached": false,
"credits_remaining": 4871,
"input": "24.7563, 46.6295"
}
cached: true means the result was served from our cache — it still counts as one credit but returns in milliseconds. credits_remaining is null for bring-your-own-key accounts.
Code examples
curl -X POST https://your-host/api/v1/lookup \
-H "X-API-Key: sat_YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{"input": "24.7136, 46.6753", "language": "en"}'
Errors
Errors return a non-2xx status and a JSON body with an error code and human-readable message.
| Status | error | Meaning |
|---|---|---|
| 400 | input_required | Missing or unparseable input. |
| 401 | api_key_required / invalid_api_key | Missing key, or the key is wrong / API access disabled. |
| 402 | out_of_credits | Your credit balance is 0. Top up to continue. |
| 403 | account_suspended | The account is suspended. |
| 429 | rate_limited | Too many requests — see Retry-After header. |
| 502 | lookup_failed | No provider could resolve the point. No credit is charged. |
You are only charged for successful lookups. Failed and invalid requests never consume a credit.
Rate limits
The API allows up to 120 requests per minute per account. Exceeding it returns 429 with a Retry-After header (seconds). Need a higher limit for a bulk job? Contact us. Repeated identical lookups are served from cache and are much faster.
Credits & billing
Each successful lookup deducts 1 credit from your account's shared balance (web dashboard + API draw from the same pool). Buy credit packs in the Console → Billing tab. Watch credits_remaining in each response, and top up before you hit zero to avoid 402 errors.
Security best practices
- Call the API from your backend server only. Never embed the key in a mobile app, browser JavaScript, or public repo.
- Store the key in an environment variable / secrets manager — not in source code.
- Always use HTTPS (the API rejects plain HTTP at the proxy).
- Rotate the key immediately if you suspect it leaked — regenerating instantly invalidates the old one.
- Disable API access from the Console when you're not using it; the key is preserved and can be re-enabled anytime.
Ready to integrate?
Generate your key in the console and make your first call in minutes.