Places by name
Wherever the API accepts a country, a city or a district, you can send an id, a code or a name in Arabic or English. This lets your website pass what the customer typed or picked without keeping your own copy of the places catalogue. It also means a wrong name has to fail loudly and helpfully, which is what this guide is about.
pickupandrecipientofPOST /shipments, and therecipientaddress ofPUT /shipments/{trackingNumber}.pickupandrecipientofPOST /pricing/quote(the district is optional there).- The
addressof a merchant and the saved addresses of a merchant. - The query parameters
country,cityanddistrictof the geography endpoints, and thecityfilter ofGET /shipments.
| Level | What you may send |
|---|---|
| Country | The id, the two-letter ISO code (SA, case does not matter), or the Arabic or English name. Optional when the city name is unambiguous |
| City | The id, the city code (unique within its country), or the Arabic or English name |
| District | The id, the district code, or the Arabic or English name. Matched inside the city that was resolved |
An id (the UUID returned by the geography endpoints) is accepted at every level, everywhere a place is accepted: creating and updating shipments, price quotes, merchant addresses and the geography and shipment list filters. An id always wins over a name. Nothing is ever created from an API call. If a place does not exist, you get an error, never a new record.
The name you send is normalised and compared with the normalised Arabic and English names of the catalogue. The comparison is an exact match on the normalised form, so spelling variants match, and a genuinely different spelling does not. Normalisation:
- ignores case and diacritics (tashkeel, tatweel);
- unifies the hamza forms
أ إ آtoا,ىtoي, andةtoه, soجدهfindsجدةandمكهfindsمكة; - converts Arabic-Indic digits to Latin digits and turns punctuation into spaces;
- removes generic place words at the start or end:
حي,مدينة,منطقة,قرية,محافظة,district,city,area,town,neighborhood, and similar; - removes the Arabic article
الfrom each word, and a separatealorel.
So all of these reach the same district:
| You send | Matches |
|---|---|
حي البرية |
البرية (leading حي is dropped) |
البريه |
البرية (ة and ه are the same) |
Al Rawdah, rawdah, AL-RAWDAH |
الروضة / Al Rawdah |
district Olaya |
العليا / Al Olaya |
Two limits to know: an attached Latin article (alrawdah) is not recognised, and a typo is not matched (العلايا is not العليا). Typos are not guessed silently because a wrong guess would send a parcel to the wrong place. Instead you get suggestions, below.
The answer is 422 with one of geo_country_not_found, geo_city_not_found or geo_district_not_found. details carries everything you need to help the user:
| Field | Meaning |
|---|---|
level |
country, city or district: which level failed |
input |
What you sent, so you can show it back |
field |
Which part of the request failed: pickup, recipient, address or city |
candidates |
Up to five "did you mean" suggestions, best first, each with id, nameAr, nameEn, score (0 to 1) and, when relevant, parentNameAr and parentNameEn |
messageAr |
The Arabic message (present when message is English) |
A real response for a recipient district with a typo:
{
"code": "geo_district_not_found",
"message": "The district was not found in the given city.",
"status": 422,
"details": {
"level": "district",
"input": "العلايا",
"candidates": [
{
"id": "c2d3e4f5-0a1b-4c2d-8e3f-4a5b6c7d8e91",
"nameAr": "العليا",
"nameEn": "Al Olaya",
"score": 0.8,
"parentNameAr": null,
"parentNameEn": null
}
],
"field": "recipient",
"messageAr": "لم يتم العثور على الحي في المدينة المحددة."
},
"traceId": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01"
}Candidates are the closest names with a similarity of at least 0.6, within the same parent: districts of the resolved city. For a city that is not found, candidates are given when you also sent the country (otherwise the whole world would be searched):
{
"code": "geo_city_not_found",
"message": "The city was not found in the given country.",
"status": 422,
"details": {
"level": "city",
"input": "جيزان",
"candidates": [
{
"id": "b7c1d2e3-4f50-4a61-8b72-93a4b5c6d7e8",
"nameAr": "جازان",
"nameEn": "Jazan",
"score": 0.8,
"parentNameAr": null,
"parentNameEn": null
}
],
"field": "city",
"messageAr": "لم يتم العثور على المدينة في الدولة المحددة."
},
"traceId": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01"
}If a name matches more than one place, nothing is chosen for you. You get geo_city_ambiguous or geo_district_ambiguous. The typical case is a city name that exists in two countries; the candidates then carry the country in parentNameAr and parentNameEn:
{
"code": "geo_city_ambiguous",
"message": "The city name matches more than one city. Specify the country or use the id.",
"status": 422,
"details": {
"level": "city",
"input": "Springfield",
"candidates": [
{
"id": "11111111-1111-4111-8111-111111111111",
"nameAr": "سبرينغفيلد",
"nameEn": "Springfield",
"score": 1,
"parentNameAr": "الولايات المتحدة",
"parentNameEn": "United States"
},
{
"id": "22222222-2222-4222-8222-222222222222",
"nameAr": "سبرينغفيلد",
"nameEn": "Springfield",
"score": 1,
"parentNameAr": "أستراليا",
"parentNameEn": "Australia"
}
],
"field": "recipient",
"messageAr": "اسم المدينة يطابق أكثر من مدينة. حدّد الدولة أو استخدم المعرّف."
},
"traceId": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01"
}Fix it by sending country as well, or by sending the id of one candidate. When a city or district name matches several records and only one of them is approved, the approved one is used and it is not reported as ambiguous.
GET /geography/resolve runs the same matching without creating anything. Send at least one of country, city, district (a district needs a city). It returns the resolved ids and both names:
curl -G "https://api.goldrock.live/api/public/v1/geography/resolve" \
-H "X-API-Key: lmc_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
-H "X-API-Secret: YOUR_API_SECRET" \
--data-urlencode 'country=SA' \
--data-urlencode 'city=جده' \
--data-urlencode 'district=حي البرية'const params = new URLSearchParams({
"country": "SA",
"city": "جده",
"district": "حي البرية"
});
const response = await fetch(`https://api.goldrock.live/api/public/v1/geography/resolve?${params}`, {
method: "GET",
headers: {
"X-API-Key": "lmc_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"X-API-Secret": "YOUR_API_SECRET"
},
});
const data = await response.json();
console.log(response.status, data);<?php
$url = 'https://api.goldrock.live/api/public/v1/geography/resolve?' . http_build_query([
'country' => 'SA',
'city' => 'جده',
'district' => 'حي البرية',
]);
$ch = curl_init($url);
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'X-API-Key: lmc_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx',
'X-API-Secret: YOUR_API_SECRET',
],
]);
$result = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
var_dump($status, json_decode($result, true));import requests
response = requests.request(
"GET",
"https://api.goldrock.live/api/public/v1/geography/resolve",
headers={
"X-API-Key": "lmc_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"X-API-Secret": "YOUR_API_SECRET",
},
params={
"country": "SA",
"city": "جده",
"district": "حي البرية",
},
timeout=30,
)
print(response.status_code, response.json()){
"country": {
"id": "5a6f7c1c-1a3e-4c1f-9d5c-3f0d7d2a1b01",
"nameAr": "المملكة العربية السعودية",
"nameEn": "Saudi Arabia"
},
"city": {
"id": "a1d3c2b4-0e7f-4f5a-8a62-9c1e2d3b4a05",
"nameAr": "جدة",
"nameEn": "Jeddah"
},
"district": {
"id": "e4b7a9d2-6c13-4d8e-b1f0-2a5c7e9f3b18",
"nameAr": "البرية",
"nameEn": "Al Bariyah"
}
}On failure it answers the same 422 errors as above. Use the ids it returns in your later calls: they are unambiguous and skip matching.
These endpoints need the geography:read scope and are paginated (Conventions):
| Endpoint | Returns |
|---|---|
GET /geography/countries |
Active, approved countries |
GET /geography/cities?country=SA |
Cities of a country. Includes your company's own pending cities (pending: true) |
GET /geography/districts?city=Riyadh&country=SA |
Districts of a city, with search to filter. Includes your pending districts |
GET /geography/coverage/cities |
The cities your company serves, with delivery and pickup flags |
GET /geography/coverage?city=Jeddah |
Whether the company delivers to and picks up from one city |
curl -G "https://api.goldrock.live/api/public/v1/geography/districts" \
-H "X-API-Key: lmc_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
-H "X-API-Secret: YOUR_API_SECRET" \
--data-urlencode 'country=SA' \
--data-urlencode 'city=Riyadh' \
--data-urlencode 'search=olaya'const params = new URLSearchParams({
"country": "SA",
"city": "Riyadh",
"search": "olaya"
});
const response = await fetch(`https://api.goldrock.live/api/public/v1/geography/districts?${params}`, {
method: "GET",
headers: {
"X-API-Key": "lmc_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"X-API-Secret": "YOUR_API_SECRET"
},
});
const data = await response.json();
console.log(response.status, data);<?php
$url = 'https://api.goldrock.live/api/public/v1/geography/districts?' . http_build_query([
'country' => 'SA',
'city' => 'Riyadh',
'search' => 'olaya',
]);
$ch = curl_init($url);
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'X-API-Key: lmc_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx',
'X-API-Secret: YOUR_API_SECRET',
],
]);
$result = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
var_dump($status, json_decode($result, true));import requests
response = requests.request(
"GET",
"https://api.goldrock.live/api/public/v1/geography/districts",
headers={
"X-API-Key": "lmc_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"X-API-Secret": "YOUR_API_SECRET",
},
params={
"country": "SA",
"city": "Riyadh",
"search": "olaya",
},
timeout=30,
)
print(response.status_code, response.json())A catalogue city is not necessarily a city your company serves. GET /geography/coverage answers for one city: delivery is true when the city belongs to an active pricing zone (or its country to an international zone) or is covered by an active branch with a delivery role, and pickup is true when an active branch covers it with a pickup role.
curl -G "https://api.goldrock.live/api/public/v1/geography/coverage" \
-H "X-API-Key: lmc_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
-H "X-API-Secret: YOUR_API_SECRET" \
--data-urlencode 'country=SA' \
--data-urlencode 'city=Jeddah'const params = new URLSearchParams({
"country": "SA",
"city": "Jeddah"
});
const response = await fetch(`https://api.goldrock.live/api/public/v1/geography/coverage?${params}`, {
method: "GET",
headers: {
"X-API-Key": "lmc_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"X-API-Secret": "YOUR_API_SECRET"
},
});
const data = await response.json();
console.log(response.status, data);<?php
$url = 'https://api.goldrock.live/api/public/v1/geography/coverage?' . http_build_query([
'country' => 'SA',
'city' => 'Jeddah',
]);
$ch = curl_init($url);
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'X-API-Key: lmc_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx',
'X-API-Secret: YOUR_API_SECRET',
],
]);
$result = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
var_dump($status, json_decode($result, true));import requests
response = requests.request(
"GET",
"https://api.goldrock.live/api/public/v1/geography/coverage",
headers={
"X-API-Key": "lmc_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"X-API-Secret": "YOUR_API_SECRET",
},
params={
"country": "SA",
"city": "Jeddah",
},
timeout=30,
)
print(response.status_code, response.json()){
"city": {
"id": "a1d3c2b4-0e7f-4f5a-8a62-9c1e2d3b4a05",
"nameAr": "جدة",
"nameEn": "Jeddah"
},
"delivery": true,
"pickup": false
}Use GET /geography/coverage/cities to fill a city dropdown with only the places you really serve:
curl -G "https://api.goldrock.live/api/public/v1/geography/coverage/cities" \
-H "X-API-Key: lmc_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
-H "X-API-Secret: YOUR_API_SECRET" \
--data-urlencode 'country=SA' \
--data-urlencode 'pageSize=100'const params = new URLSearchParams({
"country": "SA",
"pageSize": "100"
});
const response = await fetch(`https://api.goldrock.live/api/public/v1/geography/coverage/cities?${params}`, {
method: "GET",
headers: {
"X-API-Key": "lmc_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"X-API-Secret": "YOUR_API_SECRET"
},
});
const data = await response.json();
console.log(response.status, data);<?php
$url = 'https://api.goldrock.live/api/public/v1/geography/coverage/cities?' . http_build_query([
'country' => 'SA',
'pageSize' => '100',
]);
$ch = curl_init($url);
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'X-API-Key: lmc_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx',
'X-API-Secret: YOUR_API_SECRET',
],
]);
$result = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
var_dump($status, json_decode($result, true));import requests
response = requests.request(
"GET",
"https://api.goldrock.live/api/public/v1/geography/coverage/cities",
headers={
"X-API-Key": "lmc_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"X-API-Secret": "YOUR_API_SECRET",
},
params={
"country": "SA",
"pageSize": "100",
},
timeout=30,
)
print(response.status_code, response.json())- Load once, cache. Fetch
coverage/citiesfor the city list of your form and cache it for a while. Fetch the districts of a city when the user chooses it. - Prefer choosing over typing. A dropdown or autocomplete fed by these endpoints never produces a name error, and you can send the ids.
- If you let people type (free text, spreadsheets, imports), call
GET /geography/resolvewhen the field loses focus. On422, showdetails.candidatesas buttons ("Did you mean Al Olaya?"). When the user picks one, keep itsid. - Check coverage before showing the order button:
deliveryfor the recipient city,pickupfor the pickup city. A price quote also reportsdeliverable. - Send ids when you have them. If you resolved an address earlier, send the ids in
country,cityanddistrictof the shipment. - Still handle
geo_*errors on create. The catalogue can change between your check and the order. Treat them like a failed validation and let the user choose again.
For addresses in Saudi Arabia the national short address is also required: four letters followed by four digits, for example RNBA6769. A missing or malformed one is reported against its field, for example pickup.shortAddress or recipient.shortAddress.