Overview

The Zones & Cities API provides endpoints for managing geographic boundaries, zones, and cities used in trip planning and routing. Zones represent larger geographic areas (like provinces or regions), while cities are specific locations within zones.

Authentication

Most endpoints require authentication. Admin endpoints require admin role. Include the JWT token in the Authorization header:

Authorization: Bearer YOUR_JWT_TOKEN

Zones

Get All Zones

Retrieve all zones with pagination, search, and filtering options.

Query Parameters

Page

integer

default:"1"

Page number for pagination

PageSize

integer

default:"20"

Number of items per page (max 100)

string

Search zones by name

IsActive

boolean

Filter by active status

SortBy

string

default:"name"

Sort field: name, created, or active

SortOrder

string

default:"asc"

Sort order: asc or desc

Response

Zones

array

List of zones

TotalCount

integer

Total number of zones

Page

integer

Current page number

PageSize

integer

Items per page

TotalPages

integer

Total number of pages

Example Request

curl -X GET "https://api.masareagles.com/api/admin/zones?Page=1&PageSize=20&IsActive=true&SortBy=name&SortOrder=asc" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Example Response

{
  "Zones": [
    {
      "Id": "z_001",
      "Name": "منطقة الرياض",
      "AllowIntraZoneTransport": true,
      "CountryCode": "SA",
      "IsActive": true,
      "CreatedAt": "2024-01-01T00:00:00Z",
      "UpdatedAt": "2024-02-15T10:00:00Z"
    },
    {
      "Id": "z_002",
      "Name": "المنطقة الشرقية",
      "AllowIntraZoneTransport": true,
      "CountryCode": "SA",
      "IsActive": true,
      "CreatedAt": "2024-01-01T00:00:00Z",
      "UpdatedAt": null
    }
  ],
  "TotalCount": 2,
  "Page": 1,
  "PageSize": 20,
  "TotalPages": 1
}

Get Zone by ID

Retrieve detailed information about a specific zone.

Path Parameters

zoneId

string

required

Zone unique identifier

Response

Returns a single zone object with the same structure as in the zones list.

Example Request

curl -X GET "https://api.masareagles.com/api/admin/zones/z_001" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Create Zone

Create a new zone. Admin only.

Request Body

Name

string

required

Zone name (2-100 characters)

AllowIntraZoneTransport

boolean

default:"false"

Whether trips within the zone are allowed

CountryCode

string

ISO country code (2 characters, e.g., “SA”, “AE”)

Response

string

Created zone ID

Name

string

Zone name

AllowIntraZoneTransport

boolean

Intra-zone transport setting

CountryCode

string

Country code

Message

string

Success message

Example Request

curl -X POST "https://api.masareagles.com/api/admin/zones" \
  -H "Authorization: Bearer YOUR_ADMIN_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "Name": "منطقة مكة المكرمة",
    "AllowIntraZoneTransport": true,
    "CountryCode": "SA"
  }'

Example Response

{
  "Id": "z_003",
  "Name": "منطقة مكة المكرمة",
  "AllowIntraZoneTransport": true,
  "CountryCode": "SA",
  "Message": "تم إنشاء المنطقة بنجاح"
}

Update Zone

Update zone information. Admin only.

Path Parameters

zoneId

string

required

Zone unique identifier

Request Body

Name

string

Updated zone name

AllowIntraZoneTransport

boolean

Updated intra-zone transport setting

CountryCode

string

Updated country code

IsActive

boolean

Updated active status

Example Request

curl -X PUT "https://api.masareagles.com/api/admin/zones/z_003" \
  -H "Authorization: Bearer YOUR_ADMIN_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "Name": "منطقة مكة المكرمة - محدث",
    "IsActive": true
  }'

Delete Zone

Soft delete a zone. Admin only.

Path Parameters

zoneId

string

required

Zone unique identifier

Response

Message

string

Success message

Example Request

curl -X DELETE "https://api.masareagles.com/api/admin/zones/z_003" \
  -H "Authorization: Bearer YOUR_ADMIN_JWT_TOKEN"

Validate Travel Between Zones

Validate if travel is allowed between two locations (origin and destination zones).

Request Body

OriginZoneId

string

required

Origin zone ID

DestinationZoneId

string

required

Destination zone ID

Response

IsAllowed

boolean

Whether travel is allowed between zones

Message

string

Explanation message

Example Request

curl -X POST "https://api.masareagles.com/api/zones/validate-travel" \
  -H "Content-Type: application/json" \
  -d '{
    "OriginZoneId": "z_001",
    "DestinationZoneId": "z_002"
  }'

Cities

Get All Cities

Retrieve all cities with pagination, search, and filtering. Public endpoint.

Query Parameters

Page

integer

default:"1"

Page number

PageSize

integer

default:"20"

Items per page (max 100)

string

Search cities by name

IsActive

boolean

Filter by active status

ZoneId

string

Filter by zone ID

SortBy

string

default:"name"

Sort field: name, created, or active

SortOrder

string

default:"asc"

Sort order: asc or desc

Response

Cities

array

List of cities

TotalCount

integer

Total number of cities

Page

integer

Current page

PageSize

integer

Items per page

TotalPages

integer

Total pages

Example Request

curl -X GET "https://api.masareagles.com/api/cities?Page=1&PageSize=20&ZoneId=z_001&IsActive=true"

Example Response

{
  "Cities": [
    {
      "Id": "c_001",
      "Name": "الرياض",
      "Latitude": 24.7136,
      "Longitude": 46.6753,
      "ZoneId": "z_001",
      "ZoneName": "منطقة الرياض",
      "BoundingBox": [24.4, 46.4, 25.0, 47.0],
      "GeoJson": null,
      "Importance": 1.0,
      "IsActive": true,
      "CreatedAt": "2024-01-01T00:00:00Z",
      "UpdatedAt": null
    }
  ],
  "TotalCount": 1,
  "Page": 1,
  "PageSize": 20,
  "TotalPages": 1
}

Get City by ID

Retrieve detailed information about a specific city.

Path Parameters

cityId

string

required

City unique identifier

Example Request

curl -X GET "https://api.masareagles.com/api/cities/c_001"

Create City

Create a new city. Admin only.

Request Body

Name

string

required

City name (2-100 characters)

Latitude

decimal

City latitude (-90 to 90)

Longitude

decimal

City longitude (-180 to 180)

ZoneId

string

Associated zone ID

BoundingBox

array

Geographic bounding box [minLat, minLon, maxLat, maxLon]

GeoJson

string

GeoJSON string representing city boundaries

Importance

decimal

City importance (0.0 to 1.0)

Response

string

Created city ID

Name

string

City name

Message

string

Success message

Example Request

curl -X POST "https://api.masareagles.com/api/cities" \
  -H "Authorization: Bearer YOUR_ADMIN_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "Name": "جدة",
    "Latitude": 21.5433,
    "Longitude": 39.1728,
    "ZoneId": "z_002",
    "BoundingBox": [21.3, 39.0, 21.8, 39.4],
    "Importance": 0.95
  }'

Update City

Update city information. Admin only.

Path Parameters

cityId

string

required

City unique identifier

Request Body

Same parameters as Create City, all optional.

IsActive

boolean

Set city active status

Example Request

curl -X PUT "https://api.masareagles.com/api/cities/c_001" \
  -H "Authorization: Bearer YOUR_ADMIN_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "Name": "الرياض - محدث",
    "Importance": 1.0,
    "IsActive": true
  }'

Delete City

Soft delete a city. Admin only.

Path Parameters

cityId

string

required

City unique identifier

Example Request

curl -X DELETE "https://api.masareagles.com/api/cities/c_001" \
  -H "Authorization: Bearer YOUR_ADMIN_JWT_TOKEN"

Get Cities for Map

Get cities optimized for map display with minimal data.

Response

Returns a simplified list of cities with only essential fields: ID, Name, Latitude, Longitude, IsActive.

Example Request

curl -X GET "https://api.masareagles.com/api/cities/map"

Get Available Destinations

Get available destination cities from a specific origin city.

Query Parameters

OriginCityId

string

required

Origin city ID

Response

AvailableDestinations

array

List of reachable destination cities

Example Request

curl -X GET "https://api.masareagles.com/api/cities/available-destinations?OriginCityId=c_001"

Error Responses

All endpoints may return the following error responses:

message

string

Error message in Arabic or English

errors

array

Detailed validation errors

Common Error Codes

400 Bad Request - Invalid request parameters or validation errors
401 Unauthorized - Missing or invalid authentication token
403 Forbidden - Insufficient permissions (admin role required)
404 Not Found - Zone or city not found
409 Conflict - Duplicate zone/city name
500 Internal Server Error - Server error

Example Error Response

{
  "message": "فشل التحقق من صحة البيانات",
  "errors": [
    {
      "field": "Name",
      "message": "اسم المنطقة مطلوب"
    }
  ]
}

Notes

Zone Validation

Zones control inter-city travel permissions
AllowIntraZoneTransport determines if trips within the same zone are allowed
Cross-zone travel is validated using the /zones/validate-travel endpoint

City Boundaries

Cities can have both simple coordinates (Latitude/Longitude) and complex boundaries (GeoJSON)
BoundingBox provides a simple rectangular boundary for quick filtering
GeoJson provides precise polygon boundaries for accurate location checking
Importance helps prioritize cities in autocomplete and search results

Best Practices

Always validate travel between cities before creating trips
Use bounding boxes for initial filtering, then GeoJSON for precise validation
Cache city and zone data in client applications to reduce API calls
Sort by importance when displaying city search results to users

Overview

Identity Service

Users Service

Trips Service

Wallet & Payments

Admin APIs

Notifications

​Overview

​Authentication

​Zones

​Get All Zones

​Query Parameters

​Response

​Example Request

​Example Response

​Get Zone by ID

​Path Parameters

​Response

​Example Request

​Create Zone

​Request Body

​Response

​Example Request

​Example Response

​Update Zone

​Path Parameters

​Request Body

​Example Request

​Delete Zone

​Path Parameters

​Response

​Example Request

​Validate Travel Between Zones

​Request Body

​Response

​Example Request

​Cities

​Get All Cities

​Query Parameters

​Response

​Example Request

​Example Response

​Get City by ID

​Path Parameters

​Example Request

​Create City

​Request Body

​Response

​Example Request

​Update City

​Path Parameters

​Request Body

​Example Request

​Delete City

​Path Parameters

​Example Request

​Get Cities for Map

​Response

​Example Request

​Get Available Destinations

​Query Parameters

​Response

​Example Request

​Error Responses

​Common Error Codes

​Example Error Response

​Notes

​Zone Validation

​City Boundaries

​Best Practices

Build docs developers (and LLMs) love

Overview

Authentication

Zones

Get All Zones

Query Parameters

Response

Example Request

Example Response

Get Zone by ID

Path Parameters

Response

Example Request

Create Zone

Request Body

Response

Example Request

Example Response

Update Zone

Path Parameters

Request Body

Example Request

Delete Zone

Path Parameters

Response

Example Request

Validate Travel Between Zones

Request Body

Response

Example Request

Cities

Get All Cities

Query Parameters

Response

Example Request

Example Response

Get City by ID

Path Parameters

Example Request

Create City

Request Body

Response

Example Request

Update City

Path Parameters

Request Body

Example Request

Delete City

Path Parameters

Example Request

Get Cities for Map

Response

Example Request

Get Available Destinations

Query Parameters

Response

Example Request

Error Responses

Common Error Codes

Example Error Response

Notes

Zone Validation

City Boundaries

Best Practices