Areas & Pricing

Wasal addresses are built from a hierarchy of areas — Governorate → Neighborhood → Block → Street → Parcel — each identified by a stable ID. You reference these IDs when creating customer addresses, and you can query live delivery pricing per area.

Area lookup

GET /integration/merchant/governorate-area

Public — no API key required.

Lists areas at one level of the hierarchy. This is the primary endpoint for building cascading address selectors — fetch governorates first, then the neighborhoods within a governorate, then (optionally) blocks/streets/parcels.

Query parameters:

Param	Default	Description
featureType	Neighborhood	Level to list: Governorate, Neighborhood, Block, Street, Parcel.
parentId	—	Restrict to children of a specific parent area.
governorateId	—	Filter by governorate.
neighborhoodId	—	Filter by neighborhood.
blockId	—	Filter by block.
streetId	—	Filter by street.
includeGeometry	false	Set true to include GeoJSON geometry (larger payload).

Example — list all governorates:

curl "https://www.wasal.org/api/v1/integration/merchant/governorate-area?featureType=Governorate"

Example — list neighborhoods in a governorate:

curl "https://www.wasal.org/api/v1/integration/merchant/governorate-area?featureType=Neighborhood&governorateId=<governorate-id>"

Example — list blocks in a neighborhood:

curl "https://www.wasal.org/api/v1/integration/merchant/governorate-area?featureType=Block&neighborhoodId=<neighborhood-id>"

Response: the matching areas under data.list. Each item includes:

Field	Description
sourceId	Stable area ID — use as governorateId, neighborhoodId, blockId, streetId, or parcelId depending on its featureType.
featureType	Governorate, Neighborhood, Block, Street, or Parcel.
title	{ en, ar } display name.
governorateId / neighborhoodId / blockId / streetId / parcelId	The full hierarchy this area belongs to.
governorateName … parcelName	{ en, ar } names for each level.
civilId	PACI civil number (parcels).
centroid	GeoJSON point at the area's center.

Required for pricing

Every customer address must include governorateId and neighborhoodId — the delivery fee is resolved from these two fields. Including blockId as well is strongly preferred: it improves pricing and routing accuracy. An address missing the governorate or neighborhood cannot be priced and the order will be rejected.

Civil ID lookup

GET /integration/merchant/governorate-area/civil-id

Public — no API key required.

Resolves a Kuwait Civil ID (PACI) parcel number to its full area hierarchy. Useful when a customer provides their PACI number — you get back the governorate, neighborhood, block, street and parcel in one call.

Query parameter:

Param	Required	Description
civilId	Yes	The numeric PACI parcel/civil number.

Example:

curl "https://www.wasal.org/api/v1/integration/merchant/governorate-area/civil-id?civilId=12345678"

Response:

{
  "success": true,
  "data": {
    "parcel": {
      "sourceId": "...",
      "featureType": "Parcel",
      "governorateId": "...", "governorateName": { "en": "...", "ar": "..." },
      "neighborhoodId": "...", "neighborhoodName": { "en": "...", "ar": "..." },
      "blockId": "...", "blockName": { "en": "...", "ar": "..." },
      "streetId": "...", "streetName": { "en": "...", "ar": "..." },
      "parcelId": "...", "civilId": 12345678,
      "centroid": { "type": "Point", "coordinates": [47.97, 29.37] }
    }
  }
}

data.parcel is null if no parcel matches the given civil ID. Use the returned governorateId / neighborhoodId / blockId directly when creating the customer address.

Pricing

GET /integration/merchant/pricing

Requires API key.

Returns the delivery pricing zones configured for your merchant. Use this to display the delivery fee to the customer before they confirm an order.

The response lists each pricing zone with its associated governorates/neighborhoods and fee. The exact fee charged on an order is also computed automatically by the order endpoint — if you omit pricing.deliveryFee when creating an order, Wasal resolves it from the matching zone for the customer's address.

If you want a live fee quote for a specific area before order creation, call this endpoint and match the customer's governorateId / neighborhoodId against the returned zones, or simply create the order and read back the resolved fee.