GROperator

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.

  • pickup and recipient of POST /shipments, and the recipient address of PUT /shipments/{trackingNumber}.
  • pickup and recipient of POST /pricing/quote (the district is optional there).
  • The address of a merchant and the saved addresses of a merchant.
  • The query parameters country, city and district of the geography endpoints, and the city filter of GET /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 separate al or el.

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:

JSON
{
  "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):

JSON
{
  "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:

JSON
{
  "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:

GET /geography/resolve
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=حي البرية'
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
GET /geography/districts
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'

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.

GET /geography/coverage
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'
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:

GET /geography/coverage/cities
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'
  1. Load once, cache. Fetch coverage/cities for the city list of your form and cache it for a while. Fetch the districts of a city when the user chooses it.
  2. Prefer choosing over typing. A dropdown or autocomplete fed by these endpoints never produces a name error, and you can send the ids.
  3. If you let people type (free text, spreadsheets, imports), call GET /geography/resolve when the field loses focus. On 422, show details.candidates as buttons ("Did you mean Al Olaya?"). When the user picks one, keep its id.
  4. Check coverage before showing the order button: delivery for the recipient city, pickup for the pickup city. A price quote also reports deliverable.
  5. Send ids when you have them. If you resolved an address earlier, send the ids in country, city and district of the shipment.
  6. 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.