
20-11-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:
| Field | Example | Notes |
|---|---|---|
| Building number | 2919 | 4 digits |
| Street name | King Fahd Road | Arabic and English |
| District | Al Olaya | |
| City | Riyadh | |
| Postal code | 12212 | 5 digits |
| Additional number | 7845 | 4 digits, distinguishes buildings |
| Unit number | 12 | For apartments and offices |
| Short address | RAAA2919 | 4 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:
| Service | What it does | Typical use |
|---|---|---|
| National Address by short address | Expands a short code into the full address | Checkout autofill |
| Verify short address | Confirms a short code exists | Form validation |
| Verify full address | Checks building number, postal code and additional number | B2B onboarding, invoicing |
| Geocode by short address | Returns latitude and longitude | Delivery routing, maps |
| Reverse geocode | Finds 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 OTP | One-tap checkout |
| Lookups | Lists regions, cities and districts | Dropdowns 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:
- Customer enters a short address, or taps "use my location" or "use my phone number".
- Your backend calls the SPL API with your server-side API key. The key never goes to the browser or mobile app.
- SPL returns the full address and coordinates in Arabic and English.
- Your checkout shows the result for the customer to confirm, with a field for the unit or apartment number.
- The verified address is stored as structured fields, not one text blob.
- 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.
| Situation | Plugin | Custom integration |
|---|---|---|
| One online store, standard checkout | Good fit | Not needed |
| Mobile app plus web checkout | Partial | Better |
| Address must reach ERP, CRM and ZATCA invoicing | Limited | Needed |
| Logistics routing and driver apps | No | Needed |
| Address-by-phone with OTP | Varies | Full control |
| Arabic-first UX with custom validation | Limited | Full 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.
Continue Reading
Discover our full range of services - from custom software development to complete marketing solutions

Saudi Government API Integration Guide (2026): ZATCA, Qiwa, Mudad, NAFATH, Absher, Ejar, Wafi, and Payment APIs
A single map of every major Saudi government and platform integration for software teams: what each one does, who can get access, which apps need it, how the integration layer should be built, and what it costs in SAR.

NAFATH API Integration Software Development in Saudi Arabia: National SSO Login, Identity Verification, and Access Planning (2026)
Developer guide to NAFATH integration in Saudi Arabia: how the national single sign-on approval flow works, who can get access, architecture for login and identity checks, and build costs in SAR.

Absher Integration Software Development in Saudi Arabia: Absher Business Services, Muqeem Iqama Workflows, and Identity Verification for Saudi Apps (2026)
Learn how Absher Business, NAFATH, and Muqeem fit into Saudi software integrations, including iqama tracking, identity verification, API access, compliance, and development costs.

Yakeen and Maroof API Integration in Saudi Arabia: Customer and Business Verification for KSA Apps (2026)
How Yakeen identity checks, Wathq commercial registration data and the Maroof-to-Business-Platform change fit into Saudi app onboarding, with the access you need, the architecture, and PDPL controls.

