This API provides methods to interact with the core addressing data model such as creating, reading, updating and deleting address objects as well as querying them and keeping them in sync with application data and external copies/cached data.
The API supports integration with several third-party Geographic Information System (GIS) platforms via standard open protocols:
Selecting the right technologies is crucial for efficient APIimplementation. Two primary technologies are recommended:
From the outset, the technical approach involves utilising:
This structure aims to enhance the National Addressing System's functionality, supporting accurate and efficient data management and integration across various platforms.
To ensure reliable, scalable, and fair access to the NAS API ecosystem—particularly as integrations expand to include both public and private third-party systems—the platform should adopt additional operational controls and developer support mechanisms:
The NAS API layer will benefit from the implementation of rate limiting to prevent abuse, ensure equitable resource allocation, and protect backend systems from overload during periods of high demand. Rate limiting policies will be clearly defined in API documentation and enforced per API client or token, with the flexibility to grant higher limits to critical government and infrastructure partners.
Complementing rate limiting, API-level caching mechanisms (e.g., in-memory caches, reverse proxies, or CDN-based edge caching) will be deployed to accelerate the most frequently accessed data and reduce repeated queries to the primary database. Caching strategies will be tailored according to data volatility and use-case, balancing data freshness against system responsiveness.
For all external integrations, especially those with business-critical third-party systems, formal Service Level Agreements (SLAs) will be established. SLAs will define key parameters such as guaranteed uptime, target response times, maintenance notification windows, and escalation procedures for incidents. This transparency fosters trust among stakeholders and ensure predictable quality of service for mission-critical operations.
To guide system sizing and support future growth, the NAS API and underlying infrastructure will be subject to regular performance benchmarking. Metrics such as average and 95th percentile response times, throughput under load, and maximum supported concurrent connections will be documented. Scalability thresholds (e.g., API requests per minute, data volume limits, user concurrency) will be specified and reviewed as usage patterns evolve.
To facilitate secure and efficient onboarding of new integrators, a sandbox environment—mirroring the production API but operating on test data—will be provided to registered developers. This environment enables third parties to prototype and validate their integrations without risk to production data or services. Comprehensive API documentation, test credentials, and sample data will be made available within the sandbox to accelerate development and troubleshooting.
The API must as minimum implement the following methods. Authentication is exempt but implicitly required for acceptable system operations.
| Tag | Method | Endpoint | Description | |
|---|---|---|---|---|
| address-unit | GET | /address-unit/read-all | Read all address units | |
| GET | /address-unit/read/{adrutid} | Read one address unit | ||
| POST | /address-unit/upsert | Insert or update an address unit | ||
| DELETE | /address-unit/delete/{adrutid} | Delete an address unit | ||
| POST | /address-unit/sync | Synchronise uploaded dataset with server | ||
| sub-address | GET | /sub-address/read-all | Read all sub-addresses | |
| GET | /sub-address/read/{adrutid} | Read one sub-address | ||
| POST | /sub-address/upsert | Insert or update a sub-address | ||
| DELETE | /sub-address/delete/{adrutid} | Delete a sub-address | ||
| POST | /sub-address/sync | Synchronise uploaded dataset with server | ||
| street | GET | /street/read-all | Read all streets | |
| GET | /street/read/{adrutid} | Read one street | ||
| POST | /street/upsert | Insert or update a street | ||
| DELETE | /street/delete/{adrutid} | Delete a street | ||
| POST | /street/sync | Synchronise uploaded dataset with server | ||
| street-segment | GET | /street-segment/read-all | Read all street segments | |
| GET | /street-segment/read/{adrutid} | Read one street segment | ||
| POST | /street-segment/upsert | Insert or update a street segment | ||
| DELETE | /street-segment/delete/{adrutid} | Delete a street segment | ||
| POST | /street-segment/sync | Synchronise uploaded dataset with server | ||
| issues | GET | /issues/read-all | Read all issues | |
| GET | /issues/read/{adrutid} | Read one issue | ||
| POST | /issues/upsert | Insert or update an issue | ||
| DELETE | /issues/delete/{adrutid} | Delete an issue | ||
| POST | /issues/sync | Synchronise uploaded dataset with server | ||
| start-stop | GET | /start-stop/read-all | Read all start-stop points | |
| GET | /start-stop/read/{adrutid} | Read one start-stop point | ||
| POST | /start-stop/upsert | Insert or update a start-stop point | ||
| DELETE | /start-stop/delete/{adrutid} | Delete a start-stop point | ||
| POST | /start-stop/sync | Synchronise uploaded dataset with server | ||
| query | ||||
| GET | /query/free-text | |||
| GET | /query/streets | |||
| GET | /query/wilayat | |||
| GET | /query/governorate | |||
| download | GET | /download/all | ||
| GET | /download/changes/{since} |
A reference implementation of the API has been prepared and may be used directly or built on when implementing the final system