GROperator

Geography

Every operation of the LastMile Public API, generated from the OpenAPI document. The reference text is in English in both languages.

GET

/api/public/v1/geography/cities

#

List cities, optionally of one country

API key + secret, or bearer tokenRequired scope: geography:read

Active approved cities plus your company's own pending cities (pending: true). Paginated; scope geography:read.

Parameters

NameInTypeDescription
countryquerystring

Optional country: id, ISO code (e.g. SA) or name in Arabic or English.

pagequeryinteger (int32)
Default: 1

Page number, starting at 1.

pageSizequeryinteger (int32)
Default: 25

Items per page, 1 to 100 (larger values are clamped to 100).

searchquerystring

Optional text matched against the Arabic name, English name and city code.

Request example

GET /geography/cities
curl "https://apiv1.groperator.com/api/public/v1/geography/cities" \
  -H "X-API-Key: lmc_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "X-API-Secret: YOUR_API_SECRET"

Samples use an API key; replace the placeholders. To use a bearer token instead, send Authorization: Bearer <accessToken>.

Responses

200A page of cities.

Responses · Field
FieldTypeDescription
items
required
array<PublicCityDto>

Items of the requested page.

id
items[].id
required
string (uuid)

City id.

nameAr
items[].nameAr
required
string

Arabic name.

nameEn
items[].nameEn
required
string

English name.

code
items[].code
stringnullable

City code (unique within its country), when defined.

countryId
items[].countryId
required
string (uuid)

Id of the country the city belongs to.

pending
items[].pending
required
boolean

True for a city created by your company that the platform has not approved yet.

page
required
integer (int32)

Current page number, starting at 1.

pageSize
required
integer (int32)

Requested page size (1 to 100, default 25).

totalCount
required
integer (int32)

Total number of items across all pages.

totalPages
required
integer (int32)

Total number of pages.

200 · Example response
{
  "items": [
    {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "nameAr": "string",
      "nameEn": "string",
      "countryId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "pending": false
    }
  ],
  "page": 1,
  "pageSize": 1,
  "totalCount": 1,
  "totalPages": 1
}
StatusDescription
400

The request is invalid (code validation_failed, details.errors lists every field).

401

Authentication is missing or invalid (code unauthorized).

403

The credential lacks the required scope, or the public API is disabled (codes forbidden, channel_disabled).

422

The country could not be resolved (geo_country_not_found).

429

Too many requests (code rate_limited); wait for the Retry-After header.

Error responses share one body, described in the error reference. Error reference

GET

/api/public/v1/geography/countries

#

List countries

API key + secret, or bearer tokenRequired scope: geography:read

Only active, approved countries. Paginated; scope geography:read.

Parameters

NameInTypeDescription
pagequeryinteger (int32)
Default: 1

Page number, starting at 1.

pageSizequeryinteger (int32)
Default: 25

Items per page, 1 to 100 (larger values are clamped to 100).

searchquerystring

Optional text matched against the Arabic name, English name and ISO code.

Request example

GET /geography/countries
curl "https://apiv1.groperator.com/api/public/v1/geography/countries" \
  -H "X-API-Key: lmc_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "X-API-Secret: YOUR_API_SECRET"

Samples use an API key; replace the placeholders. To use a bearer token instead, send Authorization: Bearer <accessToken>.

Responses

200A page of countries.

Responses · Field
FieldTypeDescription
items
required
array<PublicCountryDto>

Items of the requested page.

id
items[].id
required
string (uuid)

Country id.

nameAr
items[].nameAr
required
string

Arabic name.

nameEn
items[].nameEn
required
string

English name.

code
items[].code
required
string

ISO 3166-1 alpha-2 code.

page
required
integer (int32)

Current page number, starting at 1.

pageSize
required
integer (int32)

Requested page size (1 to 100, default 25).

totalCount
required
integer (int32)

Total number of items across all pages.

totalPages
required
integer (int32)

Total number of pages.

200 · Example response
{
  "items": [
    {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "nameAr": "string",
      "nameEn": "string",
      "code": "string"
    }
  ],
  "page": 1,
  "pageSize": 1,
  "totalCount": 1,
  "totalPages": 1
}
StatusDescription
400

The request is invalid (code validation_failed, details.errors lists every field).

401

Authentication is missing or invalid (code unauthorized).

403

Forbidden

429

Too many requests (code rate_limited); wait for the Retry-After header.

Error responses share one body, described in the error reference. Error reference

GET

/api/public/v1/geography/coverage

#

Does the company deliver to / pick up from a city?

API key + secret, or bearer tokenRequired scope: geography:read

Delivery is true when the city is in an active pricing zone (or its country in an international zone) or covered by an active branch with a delivery role; pickup when an active branch covers it with a pickup role. Scope geography:read.

Parameters

NameInTypeDescription
countryquerystring

Optional country (id, ISO code or name); narrows an ambiguous city name.

cityquerystring

Required city: id, code or name.

Request example

GET /geography/coverage
curl -G "https://apiv1.groperator.com/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'

Samples use an API key; replace the placeholders. To use a bearer token instead, send Authorization: Bearer <accessToken>.

Responses

200Coverage of the city.

Responses · Field
FieldTypeDescription
city
required
PublicGeoNodeDto

A resolved geography node (id and both names).

id
city.id
required
string (uuid)

Resolved id.

nameAr
city.nameAr
required
string

Arabic name.

nameEn
city.nameEn
required
string

English name.

delivery
required
boolean

True when the company delivers to the city.

pickup
required
boolean

True when the company picks up from the city.

200 · Example response
{
  "city": {
    "id": "a1d3c2b4-0e7f-4f5a-8a62-9c1e2d3b4a05",
    "nameAr": "جدة",
    "nameEn": "Jeddah"
  },
  "delivery": true,
  "pickup": false
}
StatusDescription
400

city is missing.

401

Authentication is missing or invalid (code unauthorized).

403

The credential lacks the required scope, or the public API is disabled (codes forbidden, channel_disabled).

422

Country or city could not be resolved.

429

Too many requests (code rate_limited); wait for the Retry-After header.

Error responses share one body, described in the error reference. Error reference

GET

/api/public/v1/geography/coverage/cities

#

List the cities the company covers

API key + secret, or bearer tokenRequired scope: geography:read

Active approved cities with delivery and pickup flags. Paginated; scope geography:read.

Parameters

NameInTypeDescription
countryquerystring

Optional country filter (id, ISO code or name).

pagequeryinteger (int32)
Default: 1

Page number, starting at 1.

pageSizequeryinteger (int32)
Default: 25

Items per page, 1 to 100 (larger values are clamped to 100).

searchquerystring

Optional text matched against names and city code.

Request example

GET /geography/coverage/cities
curl -G "https://apiv1.groperator.com/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'

Samples use an API key; replace the placeholders. To use a bearer token instead, send Authorization: Bearer <accessToken>.

Responses

200A page of covered cities.

Responses · Field
FieldTypeDescription
items
required
array<PublicCoveredCityDto>

Items of the requested page.

id
items[].id
required
string (uuid)

City id.

nameAr
items[].nameAr
required
string

Arabic name.

nameEn
items[].nameEn
required
string

English name.

code
items[].code
stringnullable

City code, when defined.

countryId
items[].countryId
required
string (uuid)

Country id.

delivery
items[].delivery
required
boolean

True when the company delivers to the city.

pickup
items[].pickup
required
boolean

True when the company picks up from the city.

page
required
integer (int32)

Current page number, starting at 1.

pageSize
required
integer (int32)

Requested page size (1 to 100, default 25).

totalCount
required
integer (int32)

Total number of items across all pages.

totalPages
required
integer (int32)

Total number of pages.

200 · Example response
{
  "items": [
    {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "nameAr": "string",
      "nameEn": "string",
      "countryId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "delivery": false,
      "pickup": false
    }
  ],
  "page": 1,
  "pageSize": 1,
  "totalCount": 1,
  "totalPages": 1
}
StatusDescription
400

The request is invalid (code validation_failed, details.errors lists every field).

401

Authentication is missing or invalid (code unauthorized).

403

The credential lacks the required scope, or the public API is disabled (codes forbidden, channel_disabled).

422

The country could not be resolved.

429

Too many requests (code rate_limited); wait for the Retry-After header.

Error responses share one body, described in the error reference. Error reference

GET

/api/public/v1/geography/districts

#

List the districts of a city

API key + secret, or bearer tokenRequired scope: geography:read

Active approved districts plus your company's own pending districts (pending: true). Paginated; scope geography:read.

Parameters

NameInTypeDescription
countryquerystring

Optional country (id, ISO code or name); narrows an ambiguous city name.

cityquerystring

Required city: id, code or name in Arabic or English.

pagequeryinteger (int32)
Default: 1

Page number, starting at 1.

pageSizequeryinteger (int32)
Default: 25

Items per page, 1 to 100 (larger values are clamped to 100).

searchquerystring

Optional text matched against the Arabic name, English name and district code.

Request example

GET /geography/districts
curl -G "https://apiv1.groperator.com/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'

Samples use an API key; replace the placeholders. To use a bearer token instead, send Authorization: Bearer <accessToken>.

Responses

200A page of districts.

Responses · Field
FieldTypeDescription
items
required
array<PublicDistrictDto>

Items of the requested page.

id
items[].id
required
string (uuid)

District id.

nameAr
items[].nameAr
required
string

Arabic name.

nameEn
items[].nameEn
required
string

English name.

code
items[].code
stringnullable

District code, when defined.

cityId
items[].cityId
required
string (uuid)

Id of the city the district belongs to.

pending
items[].pending
required
boolean

True for a district created by your company that the platform has not approved yet.

page
required
integer (int32)

Current page number, starting at 1.

pageSize
required
integer (int32)

Requested page size (1 to 100, default 25).

totalCount
required
integer (int32)

Total number of items across all pages.

totalPages
required
integer (int32)

Total number of pages.

200 · Example response
{
  "items": [
    {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "nameAr": "string",
      "nameEn": "string",
      "cityId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "pending": false
    }
  ],
  "page": 1,
  "pageSize": 1,
  "totalCount": 1,
  "totalPages": 1
}
StatusDescription
400

city is missing (validation_failed).

401

Authentication is missing or invalid (code unauthorized).

403

The credential lacks the required scope, or the public API is disabled (codes forbidden, channel_disabled).

422

Country or city could not be resolved (geo_* codes with candidates).

429

Too many requests (code rate_limited); wait for the Retry-After header.

Error responses share one body, described in the error reference. Error reference

GET

/api/public/v1/geography/resolve

#

Validate a location by names (or ids/codes) before creating a shipment

API key + secret, or bearer tokenRequired scope: geography:read

Returns the resolved ids and names. Nothing is ever created. When a level cannot be matched, the response is 422 with code geo_country_not_found, geo_city_not_found, geo_district_not_found, geo_city_ambiguous or geo_district_ambiguous and details = { level, input, candidates[] } with "did you mean" suggestions. At least one parameter is required; a district requires a city. Scope geography:read.

Parameters

NameInTypeDescription
countryquerystring

Country: id, ISO code or name.

cityquerystring

City: id, code or name.

districtquerystring

District: id, code or name.

Request example

GET /geography/resolve
curl -G "https://apiv1.groperator.com/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=Riyadh' \
  --data-urlencode 'district=Al Olaya'

Samples use an API key; replace the placeholders. To use a bearer token instead, send Authorization: Bearer <accessToken>.

Responses

200The resolved location.

Responses · Field
FieldTypeDescription
countryPublicGeoNodeDto

A resolved geography node (id and both names).

id
country.id
required
string (uuid)

Resolved id.

nameAr
country.nameAr
required
string

Arabic name.

nameEn
country.nameEn
required
string

English name.

cityPublicGeoNodeDto

A resolved geography node (id and both names).

id
city.id
required
string (uuid)

Resolved id.

nameAr
city.nameAr
required
string

Arabic name.

nameEn
city.nameEn
required
string

English name.

districtPublicGeoNodeDto

A resolved geography node (id and both names).

id
district.id
required
string (uuid)

Resolved id.

nameAr
district.nameAr
required
string

Arabic name.

nameEn
district.nameEn
required
string

English name.

200 · Example response
{
  "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"
  }
}
StatusDescription
400

No parameter was given.

401

Authentication is missing or invalid (code unauthorized).

403

The credential lacks the required scope, or the public API is disabled (codes forbidden, channel_disabled).

422

The location could not be resolved.

429

Too many requests (code rate_limited); wait for the Retry-After header.

Error responses share one body, described in the error reference. Error reference