Saudi Address API v1

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.

Base URL
https://your-host
Protocol
HTTPS · JSON
Auth
X-API-Key header
Cost
1 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>.

HTTP header
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

POST /api/v1/lookup

Send a JSON body with an input and an optional language.

FieldTypeRequiredDescription
inputstringYesCoordinates "24.71,46.67" or a Short Address "RCDA6608".
languagestringNo"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.

200 OK · application/json
{
  "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.

StatuserrorMeaning
400input_requiredMissing or unparseable input.
401api_key_required / invalid_api_keyMissing key, or the key is wrong / API access disabled.
402out_of_creditsYour credit balance is 0. Top up to continue.
403account_suspendedThe account is suspended.
429rate_limitedToo many requests — see Retry-After header.
502lookup_failedNo 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.

Open Console →