MyShortAddress 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.

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

The lookup endpoint

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

Input types

Search by place name

Find a place — a shop, company, mall or landmark — by its name, then look it up by the place_id you pick. Included in every paid pack; a free account can try it 3 times. The search itself uses no credit.

GET /api/v1/search?q=Kingdom%20Centre&language=en
X-API-Key: sat_...

200 OK
{
  "results": [
    { "place_id": "ChIJ...", "name": "Kingdom Centre",
      "area": "King Fahd Road, Riyadh Saudi Arabia" }
  ],
  "paid": true,
  "free_tries_left": null
}

POST /api/v1/lookup
{ "place_id": "ChIJ...", "label": "Kingdom Centre", "language": "en" }

The lookup answers exactly like any other lookup, plus place_name. Errors: 402 name_search_locked when the free tries are used up, 400 query_too_short under 3 characters.

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"
}

When the pin is not on a registered building

A Short Address belongs to a registered building. If the point is on a street, a car park or open land, you get the Short Address of the nearest registered building within 100 m, and two extra fields say so. Beyond 100 m, short_address is null and no credit is used.

{
  "short_address":      "RRRA3218",
  "nearest": {
    "short_address":    "RRRA3218",
    "distance_m":       23,
    "lat":              24.87922,
    "lng":              46.62253
  },
  "short_address_note": "Nearest registered building, 23 m from this point",
  "lat":                24.8791221,
  "lng":                46.6227282,
  "...":                "the other fields describe that building"
}

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"}'

import requests

resp = requests.post(
    "https://your-host/api/v1/lookup",
    headers={"X-API-Key": "sat_YOUR_KEY"},
    json={"input": "24.7136, 46.6753", "language": "en"},
    timeout=15,
)
resp.raise_for_status()
data = resp.json()
print(data["short_address"], "-", data["formatted"])

const res = await fetch("https://your-host/api/v1/lookup", {
  method: "POST",
  headers: {
    "X-API-Key": "sat_YOUR_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ input: "24.7136, 46.6753", language: "en" }),
});
const data = await res.json();
console.log(data.short_address, "-", data.formatted);

<?php
$ch = curl_init("https://your-host/api/v1/lookup");
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_POST           => true,
  CURLOPT_HTTPHEADER     => [
    "X-API-Key: sat_YOUR_KEY",
    "Content-Type: application/json",
  ],
  CURLOPT_POSTFIELDS => json_encode([
    "input" => "24.7136, 46.6753", "language" => "en",
  ]),
]);
$data = json_decode(curl_exec($ch), true);
echo $data["short_address"] . " - " . $data["formatted"];

import java.net.http.*;
import java.net.URI;

var client = HttpClient.newHttpClient();
var request = HttpRequest.newBuilder()
    .uri(URI.create("https://your-host/api/v1/lookup"))
    .header("X-API-Key", "sat_YOUR_KEY")
    .header("Content-Type", "application/json")
    .POST(HttpRequest.BodyPublishers.ofString(
        "{\"input\": \"24.7136, 46.6753\", \"language\": \"en\"}"))
    .build();

var response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

using System.Net.Http;
using System.Text;

var client = new HttpClient();
client.DefaultRequestHeaders.Add("X-API-Key", "sat_YOUR_KEY");

var body = new StringContent(
    "{\"input\": \"24.7136, 46.6753\", \"language\": \"en\"}",
    Encoding.UTF8, "application/json");

var resp = await client.PostAsync("https://your-host/api/v1/lookup", body);
Console.WriteLine(await resp.Content.ReadAsStringAsync());

package main

import (
    "bytes"
    "io"
    "net/http"
)

func main() {
    body := []byte(`{"input": "24.7136, 46.6753", "language": "en"}`)
    req, _ := http.NewRequest("POST", "https://your-host/api/v1/lookup", bytes.NewBuffer(body))
    req.Header.Set("X-API-Key", "sat_YOUR_KEY")
    req.Header.Set("Content-Type", "application/json")

    resp, _ := http.DefaultClient.Do(req)
    defer resp.Body.Close()
    out, _ := io.ReadAll(resp.Body)
    println(string(out))
}

require "net/http"
require "json"
require "uri"

uri = URI("https://your-host/api/v1/lookup")
req = Net::HTTP::Post.new(uri, {
  "X-API-Key" => "sat_YOUR_KEY",
  "Content-Type" => "application/json",
})
req.body = { input: "24.7136, 46.6753", language: "en" }.to_json

res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
data = JSON.parse(res.body)
puts "#{data['short_address']} - #{data['formatted']}"

Batch lookups

Have a long list? Send up to 1,000 inputs in one request instead of one request each. The batch is looked up in the background at a steady pace, and you collect the results when it's done. Billing is the same as the bulk CSV: 1 credit per new Short Address found; inputs with no Short Address, repeats and errors are free.

curl -X POST https://your-host/api/v1/batch \
  -H "X-API-Key: sat_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"inputs": ["24.7563,46.6295", "RCDA6608", "https://maps.app.goo.gl/..."], "language": "en"}'

The answer is 202 Accepted with a batch_id:

{
  "batch_id": "3f9c2a7d41e0b8c65d12",
  "status":   "queued",
  "total":    3,
  "done":     0
}

Ask every few seconds. While status is queued or running you see the progress (done of total). When it is done, results lists every input in the order you sent it, with the address fields of a single lookup plus status (it starts with ok when the address was found) and error.

{
  "batch_id": "3f9c2a7d41e0b8c65d12",
  "status":   "done",
  "total": 3, "done": 3, "ok": 2, "errors": 1, "skipped": 0,
  "results": [
    {"input": "24.7563,46.6295", "status": "ok", "short_address": "RCDA6608",
     "building_number": "6608", "street": "Anas Ibn Malik Road", "district": "Al Aqiq",
     "city": "Riyadh", "postal_code": "13515", "additional_number": "2745", "...": "..."},
    {"input": "RCDA6608", "status": "ok - free, already looked up", "...": "..."},
    {"input": "https://maps.app.goo.gl/...", "status": "error",
     "error": "This link shares a place name, not a pin on the building...", "...": "..."}
  ]
}

Stop a batch with POST /api/v1/batch/{batch_id}/cancel — inputs not looked up yet use no credit. Results stay available for 7 days. Errors: 400 inputs_required, 413 too_many_rows (over 1,000 inputs), 402 insufficient_credits (your balance is lower than the number of inputs), 429 queue_full (10,000 inputs already waiting).

Errors

Errors return a non-2xx status and a JSON body with an error code and human-readable message.

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). For a long list, send a batch of up to 1,000 inputs instead. Repeated identical lookups are served from cache and are much faster.

Credits & billing

You pay only for new addresses. 1 credit is used when a lookup returns a Short Address you haven't looked up recently. These are free:

• a lookup that finds no Short Address (no building within 100 m) — the response says "charged": false
• the same Short Address again within 7 days (free_reason: "repeat")
• place-name suggestions from /api/v1/search

The web app, bulk CSV and API draw from the same shared balance. 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.