Address validation for UAE and Saudi products: a production guide

A customer pastes an address, the map drops a pin, and the checkout marks it valid. That sequence looks sensible until a driver reaches the wrong gate, a bill loses the submitted legal text, or a Saudi P.O. Box is treated like a building.

The problem is the word valid. It can mean that text matches a postal format, an authority recognizes an identifier, a geocoder found a coordinate, a courier can serve the destination, or the customer confirmed the entrance. Those are separate claims.

For UAE and Saudi products, build an address record that can carry each claim independently. Then let checkout, onboarding, billing and field service apply different acceptance policies to the same record.

One address, five questions

A useful validation workflow answers at least five questions:

• Postal deliverability: can a postal operator or carrier route an item using this information?
• Official address: is an address or identifier recognized by the relevant authority?
• Geocoding: did a map dataset match the text to a coordinate, and at what precision?
• Entrance: which gate or building entrance should a person actually use?
• User control: what did the customer enter, review and confirm?

A precise coordinate does not prove postal deliverability. A recognized building does not prove an apartment exists. An official address does not prove the person submitting it controls the premises. Model the differences rather than hiding them behind isValid: true.

Saudi Arabia has a defined postal structure

Saudi Post | SPL lists the National Address components as building number, street, secondary number, district, five-digit postal code and city. SPL also describes a Short Address made from four letters and four numbers.

The UPU's Saudi addressing sheet, marked April 2025, separates home delivery from P.O. Box delivery. Its home-delivery format includes building number and street, an optional unit or office line, additional number and district, postcode, locality and country. A P.O. Box has its own format. That distinction should survive in your database.

Do not validate a Short Address only because it matches a letter-and-digit pattern. A pattern can reject obvious typos, but only authoritative evidence can show that the code exists and resolves to the expected destination. The SPL page mentions National Address API services, but it does not publish a contract there. Use an API only when you have current documentation and access terms.

The UAE needs emirate-aware routing

Do not build a field called uaeAddressId and expect one scheme to fill it.

In Dubai, Dubai Municipality describes Makani as a smart geo-tagging system for precise location codes and building entrances. Its linked public web-service manual documents operations named IsValidMakani, GetMakaniDetails and GetMakaniInfoFromCoord. The manual says a Makani number uniquely identifies a main entrance and shows responses containing coordinates, entrance, building, community and emirate data.

That makes Makani valuable entrance evidence. It is not an apartment number, proof of occupancy or a generic postal-deliverability result. The manual is older and documents a SOAP/WCF service, so put it behind an adapter and contract-test the live service before relying on it.

Abu Dhabi has a separate system. The Department of Municipalities and Transport says Onwani applies across the Emirate of Abu Dhabi and lists building number, street name, city, area and postal code as its address elements. Onwani signs can expose map location and directions through a QR code. The authoritative page does not publish a validation API contract, so do not manufacture one in your architecture.

Postal routing remains another layer. The UPU's UAE addressing sheet says deliveries are made to P.O. Boxes only, but the sheet is marked September 2014. Treat it as a narrow postal-format reference, not a current statement about every courier. Your carrier integration still needs its own serviceability check.

A global API will not close the gap

Google's current Address Validation API coverage table lists neither the UAE nor Saudi Arabia. Do not send production traffic for these countries and interpret an error, coarse result or different Maps product as validated deliverability.

Google's schema is still useful as a design reference because its REST documentation explicitly says a postal address is not intended to model geographical locations. Its response guide also separates validation granularity from geocode granularity. Copy that separation, not the unsupported integration.

OpenStreetMap can add map evidence, but the public Nominatim service is not a free checkout backend. Its usage policy sets an absolute maximum of one request per second, requires identifying headers and attribution, forbids client-side autocomplete, and discourages commercial dependency. The reverse-geocoding manual says it returns the closest suitable indexed OSM object rather than the exact address at the coordinate. In dense areas, that object can belong to another street.

Sources: SPL, Dubai Municipality, Abu Dhabi DMT, UPU, Google Maps Platform and OpenStreetMap documentation. Graphic: SultanByte editorial artwork.

Store evidence, not just cleaned fields

A canonical record should preserve the customer's text, normalized components and external observations. Authority-specific values belong in a namespaced list rather than overloaded postal fields.

type Country = "SA" | "AE";
type Confidence = "unknown" | "low" | "medium" | "high";
type Decision = "ACCEPT" | "CONFIRM" | "MANUAL_REVIEW" | "REJECT";

type AuthorityId = {
  scheme: "SA_NATIONAL_ADDRESS" | "SA_SHORT_ADDRESS" | "DUBAI_MAKANI" | "ABU_DHABI_ONWANI";
  value: string;
  status: "unverified" | "verified" | "not_found" | "conflict";
};

type Observation = {
  source: string;
  operation: string;
  observedAt: string;
  status: "success" | "no_match" | "unavailable" | "error";
  responseDigest?: string;
  schemaVersion?: string;
};

type AddressRecord = {
  country: Country;
  emirate?: string;
  rawInput: string;
  language?: "ar" | "en" | "mixed";
  postal: {
    addressLines: string[];
    buildingNumber?: string;
    street?: string;
    districtOrArea?: string;
    city?: string;
    postalCode?: string;
    additionalNumber?: string;
    unit?: string;
    poBox?: string;
  };
  authorityIds: AuthorityId[];
  location?: {
    lat: number;
    lng: number;
    precision: "entrance" | "building" | "street" | "area" | "unknown";
    source: string;
  };
  access?: { entranceLabel?: string; instructions?: string };
  confidence: {
    postal: Confidence;
    official: Confidence;
    geocode: Confidence;
    entrance: Confidence;
    userConfirmed: Confidence;
  };
  observations: Observation[];
  decision: Decision;
  decisionReasons: string[];
};

rawInput should be immutable. Normalize whitespace and presentation forms into separate fields, but retain Arabic and Latin-script labels as supplied. Do not silently transliterate a customer's evidence or replace their text with a geocoder's preferred label.

External responses should become observations. Record the provider, operation, time, outcome and response digest. This makes a later decision explainable without storing an entire vendor payload forever. Full addresses, coordinates and access instructions are sensitive, so keep them out of application logs. SultanByte's privacy-safe logging guide covers the same event-design principle.

Put policy after the adapters

A production pipeline can stay simple if each stage has one job:

1. Capture country first, and emirate for UAE records. Preserve the raw text.
2. Parse without inventing missing components. A parser may classify tokens, not certify them.
3. Route to country and emirate adapters. Never send an Abu Dhabi identifier to a Dubai-specific rule and call the result invalid.
4. Collect official, postal, carrier and geospatial observations separately.
5. Ask the user to review inferred corrections and confirm the map pin or entrance.
6. Apply a policy for the workflow that requested the address.

Checkout might accept a user-confirmed Dubai entrance plus unit instructions even when postal evidence is unknown. Field service may require entrance-level confidence and a contact workflow. Billing may need the exact submitted address preserved. Regulated onboarding may require an official proof process that a map pin cannot satisfy.

Wrap every external adapter with a timeout, circuit breaker and contract fixtures. A provider outage should usually produce unavailable, not invalid. Keep vendor-specific fields inside the adapter and emit your own stable observation shape.

Use statuses that operators can act on

A single percentage creates false precision. Keep confidence per dimension and make the final status operational:

• ACCEPT means the workflow's required evidence is present with no material contradiction.
• CONFIRM means the address is plausible, but the user should approve a correction, pin or entrance.
• MANUAL_REVIEW means official, postal, map or user evidence conflicts.
• REJECT is for a confirmed hard failure such as an impossible country/emirate combination, a documented identifier not found, or a known no-service destination.

Never average official: high and entrance: low into a reassuring score. Show the weak dimension and ask for the evidence the workflow actually needs.

QA cases worth automating

Build fixtures around decisions, not only parsers:

• A complete Saudi home address keeps building, district, additional number and postcode distinct.
• A Saudi P.O. Box never acquires a fake building coordinate.
• A Short Address with the right shape remains unverified until authoritative evidence arrives.
• A valid Dubai Makani entrance with no unit returns CONFIRM for apartment delivery.
• An Abu Dhabi Onwani address with a user-moved pin preserves both authority text and user-confirmed location.
• A Dubai-tagged authority response for an Abu Dhabi record becomes MANUAL_REVIEW.
• Arabic and English aliases resolve to one candidate without deleting either input form.
• A reverse geocoder returning the neighbouring street cannot overwrite entrance evidence.
• A timeout records unavailable and follows the workflow's fallback policy.
• Telemetry contains reason codes and adapter status, not raw address text or coordinates.

Replay these fixtures whenever an authority, carrier or geocoder contract changes. Track confirmation rate, manual-review rate, entrance corrections and delivery failures by evidence combination. Those metrics reveal whether a validator helps users or merely produces cleaner-looking strings.

Ship the decision record

The durable output is not a formatted address. It is a decision with supporting observations, unresolved dimensions and a record of what the user confirmed. That design can absorb better official services or map data later without rewriting every address or pretending that one provider defines truth.

Cover credit: SultanByte editorial artwork, based on official SPL, Dubai Municipality, Abu Dhabi DMT, UPU and technical documentation.