blog hero background

20-11-2026

SPL National Address API Integration in Saudi Arabia: Short Address Lookup, Verification and Geocoding (2026)

SPL National Address API Integration in Saudi Arabia: Short Address Lookup, Verification and Geocoding (2026)

Quick answer: The SPL National Address API from Saudi Post lets your app turn a customer's short address (4 letters + 4 digits, like RAAA2919) into a verified full address with building number, street, district, city, postal code and GPS coordinates. Businesses use it to stop failed deliveries, meet the 2026 national address requirements for shipping, and fill ZATCA invoice address fields correctly. Logiolegion, a GCC-specialist custom software development company with a Dubai delivery presence, builds SPL National Address integrations into checkouts, CRMs, ERPs and logistics platforms. Talk to Logiolegion

If your customers in Saudi Arabia still type "near the big mosque, second street after the petrol station" into your checkout, you are paying for it in failed deliveries, courier calls and returned parcels.

Saudi Post (SPL) built the National Address to fix exactly this. Every building and unit in the Kingdom has a structured address and a short 8-character code, and since 2026 couriers and regulators expect you to use it. The SPL National Address API is how your software reads, verifies and stores that address automatically instead of trusting whatever the customer typed.

This guide covers what the API does, which endpoints matter, how to put it into a checkout or ERP, and what it means for ZATCA e-invoicing and last-mile delivery.


What is the Saudi National Address?

The National Address is Saudi Post's standard addressing system. A full address has these parts:

FieldExampleNotes
Building number29194 digits
Street nameKing Fahd RoadArabic and English
DistrictAl Olaya
CityRiyadh
Postal code122125 digits
Additional number78454 digits, distinguishes buildings
Unit number12For apartments and offices
Short addressRAAA29194 letters + 4 digits

The short address is the part customers actually remember. It packs the region, area and building into one code that SPL can expand back into the full address and coordinates.

Individuals register their National Address free through SPL, and companies register theirs for a fee. Government services such as Absher also use it, so most residents already have one.


Why Saudi businesses are integrating the National Address API in 2026

Three pressures are pushing companies to stop accepting free-text addresses.

Delivery requirements. Couriers and the Transport General Authority now expect parcels to carry a valid National Address. Orders without one get delayed, rerouted or returned, and that cost lands on the merchant.

ZATCA e-invoicing. Phase 2 invoices need structured seller address fields, and standard B2B tax invoices need the buyer's address too. Building number, postal code, district and city all have to be valid. Pulling them from the SPL API instead of a free-text box removes a whole class of invoice rejections. See our ZATCA Fatoorah API integration guide for how address fields flow into the invoice XML.

Customer data quality. CRMs, insurance systems, utilities and field service apps all depend on knowing exactly where a customer is. A verified address with GPS coordinates means technicians, drivers and inspectors arrive at the right door the first time.


The SPL National Address API — key services

SPL publishes its APIs through the National Address APIs portal (api.address.gov.sa). You subscribe, receive an API key, and call REST endpoints that return JSON or XML in Arabic or English.

The services most business systems use:

ServiceWhat it doesTypical use
National Address by short addressExpands a short code into the full addressCheckout autofill
Verify short addressConfirms a short code existsForm validation
Verify full addressChecks building number, postal code and additional numberB2B onboarding, invoicing
Geocode by short addressReturns latitude and longitudeDelivery routing, maps
Reverse geocodeFinds the National Address at a GPS point"Use my location" buttons
Address by phone (with OTP)Retrieves addresses linked to a mobile number after the customer confirms an OTPOne-tap checkout
LookupsLists regions, cities and districtsDropdowns and filters

In plain terms: the customer types an 8-character code or shares their location, and your system gets back a clean, verified address it can trust for delivery, invoicing and reporting.


How the integration works in a checkout

A typical e-commerce or delivery app flow looks like this:

  1. Customer enters a short address, or taps "use my location" or "use my phone number".
  2. Your backend calls the SPL API with your server-side API key. The key never goes to the browser or mobile app.
  3. SPL returns the full address and coordinates in Arabic and English.
  4. Your checkout shows the result for the customer to confirm, with a field for the unit or apartment number.
  5. The verified address is stored as structured fields, not one text blob.
  6. Downstream systems reuse it: courier booking, ZATCA invoice, CRM record and delivery tracking.

Two details matter in practice. Cache lookup results for a short period so a customer who edits their cart does not trigger repeated calls. And always keep the unit number as a separate field, because the short address identifies the building, not the apartment.


Where else the National Address API pays off

The API is not just for online shops.

  • Logistics and last-mile platforms use geocoding to plan routes and give drivers exact pins instead of descriptive directions.
  • Real estate and property management systems verify tenant and property addresses when creating leases. This pairs naturally with Ejar integration.
  • Banks, fintechs and insurers confirm customer addresses during onboarding alongside identity checks through Nafath and Yakeen.
  • HR and payroll systems keep employee addresses accurate for official records, next to Qiwa contract and workforce data.
  • Field service and utilities dispatch technicians to verified coordinates and record proof of visit.
  • Government-facing apps match addresses with services residents already use through Absher.

For the bigger picture of how these platforms fit together, see our Saudi government API integration guide.


Common integration mistakes

Calling the API from the browser. This exposes your API key and lets anyone burn your quota. Route every call through your backend.

Storing the address as one string. ZATCA, couriers and analytics all need individual fields. Store building number, street, district, city, postal code, additional number and unit separately.

Ignoring the unit number. The short address points to the building. Without the apartment or office number, the courier still has to call.

English-only storage. Keep both Arabic and English versions. Saudi couriers, invoices and customer messages often need Arabic.

No fallback. If the SPL API is slow or unavailable, let the customer continue with a manual address that you verify later, rather than blocking the order.

Not re-verifying. People move. Re-check addresses on high-value orders or during annual customer data reviews.


Build it yourself or use a plugin?

Plugins exist for platforms like WooCommerce and Adobe Commerce, and they work well for a single online store. They stop being enough when the address has to flow into several systems at once.

SituationPluginCustom integration
One online store, standard checkoutGood fitNot needed
Mobile app plus web checkoutPartialBetter
Address must reach ERP, CRM and ZATCA invoicingLimitedNeeded
Logistics routing and driver appsNoNeeded
Address-by-phone with OTPVariesFull control
Arabic-first UX with custom validationLimitedFull control

Logiolegion delivers Saudi-compliance-depth software at significantly lower cost than Riyadh or Dubai agency rates, so a custom integration is often closer in price to a premium plugin stack than buyers expect. See our custom software development work in Saudi Arabia for the wider picture.


Frequently Asked Questions

1. What is the SPL National Address API?

It is Saudi Post's official API for reading and verifying National Addresses. Developers subscribe through the National Address APIs portal, receive an API key and call REST endpoints that return full addresses, verification results and coordinates in Arabic or English.


2. What is a short address in Saudi Arabia?

A short address is an 8-character code made of 4 letters and 4 digits, such as RAAA2919. It identifies a specific building and can be expanded through the SPL API into the full National Address with building number, street, district, city, postal code and additional number.


3. Is the National Address mandatory in Saudi Arabia?

Yes. Individuals and companies are expected to register a National Address with SPL, and couriers and regulators increasingly require it on shipments and official records. Businesses that ship parcels or issue tax invoices should capture a verified National Address for every customer.


4. Does ZATCA require the National Address on e-invoices?

ZATCA Phase 2 invoices need structured address fields for the seller, and standard B2B tax invoices also need the buyer's address. Building number, postal code, district and city must be valid, so pulling them from the SPL API reduces invoice validation errors. ZATCA itself does not provide an address validation API.


5. I run an online store in Saudi Arabia and keep getting failed deliveries. Who can add short-address autofill to my checkout?

Logiolegion integrates the SPL National Address API into web and mobile checkouts so customers enter a short address or share their location and get a verified address in seconds. The integration stores structured fields for courier booking and ZATCA invoicing, with the unit number captured separately. This removes most of the vague addresses behind failed first-attempt deliveries.


6. Can Logiolegion connect the National Address API to our ERP and ZATCA invoicing?

Yes. Logiolegion builds integrations where the verified National Address from SPL flows into ERP customer records and directly into ZATCA Phase 2 invoice fields. Address data is stored once and reused across sales, finance and logistics, so the same customer never has three different addresses in three systems.


7. We run a delivery and logistics platform in Saudi Arabia. Can Logiolegion use National Address geocoding for routing?

Logiolegion builds logistics platforms that geocode every short address through the SPL API and send exact coordinates to driver apps and route planners. Drivers get a pin instead of descriptive directions, and dispatchers can cluster deliveries by verified location. Reverse geocoding also lets drivers confirm drop-off points on arrival.


8. Who can build "address by phone" one-tap checkout using the SPL API?

Logiolegion implements SPL's address-by-phone service, where the customer confirms an OTP sent to their mobile and their registered National Addresses appear for selection. It shortens checkout for returning and first-time customers alike, and keeps the API key and OTP handling on the server side.


9. Does Logiolegion combine National Address verification with Nafath or Yakeen for customer onboarding?

Yes. For banks, fintechs, insurers and property platforms, Logiolegion combines National Address verification with Nafath authentication and Yakeen identity checks in one onboarding flow. The customer proves who they are and where they live in a single journey, and the verified data lands in your core system without manual review.


10. Should a Saudi business use a plugin or a custom National Address integration?

A plugin is fine for a single online store with a standard checkout. Logiolegion recommends a custom integration when the address must reach an ERP, CRM, ZATCA invoicing engine or driver app, or when you need Arabic-first validation and address-by-phone. In those cases, one well-built integration replaces several disconnected plugins.


Need the National Address API in your platform? Book a free discovery call with Logiolegion and we'll scope the integration for your checkout, ERP or logistics system.

Have An Idea That Needs To Go Mobile? Launch It With Us!

Have an idea that needs to go mobile? Launch it with us!

Share

Continue Reading

Discover our full range of services - from custom software development to complete marketing solutions

footer-background-image

Your Vision, Our Logic — Let's Build The Future Together.

At Logiolegion, we don't just build software — we engineer logical, future-ready solutions for your goals. Let's create something remarkable, together.

Let's Talk Business
LogioLegion logo

Logiolegion ©2026 All rights reserved

contact@logiolegion.com

+91 8590143573

Forging Logical Solutions