PHPackages ali-alharthi/saudiaddress - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [API Development](/categories/api) 4. / 5. ali-alharthi/saudiaddress ActiveLibrary[API Development](/categories/api) ali-alharthi/saudiaddress ========================= Saudi National Address API PHP Library with Laravel support. 2.0(4y ago)18585[1 issues](https://github.com/ali-alharthi/SaudiAddress/issues)MITPHPPHP >=7.2 Since Aug 27Pushed 4y ago1 watchersCompare [ Source](https://github.com/ali-alharthi/SaudiAddress)[ Packagist](https://packagist.org/packages/ali-alharthi/saudiaddress)[ Docs](https://github.com/ali-alharthi/saudiaddress)[ RSS](/packages/ali-alharthi-saudiaddress/feed)WikiDiscussions master Synced yesterday READMEChangelog (3)Dependencies (2)Versions (5)Used By (0) Saudi National Address API ========================== [](#saudi-national-address-api) [![Latest Version on Packagist](https://camo.githubusercontent.com/bd722961bfdbfe50f3cb1cc537ea496ddd7a7708754cf3809d693953a0a7adba/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f616c692d616c6861727468692f7361756469616464726573732e7376673f7374796c653d666c6174)](https://packagist.org/packages/ali-alharthi/saudiaddress)[![Build Status](https://camo.githubusercontent.com/b514eb214fa08d79094b8580a492c9fcd2d91ba8ae1a3abe5b5f7c85562fc73d/68747470733a2f2f696d672e736869656c64732e696f2f7363727574696e697a65722f6275696c642f672f616c692d616c6861727468692f5361756469416464726573732f6d61737465723f7374796c653d666c6174)](https://scrutinizer-ci.com/g/ali-alharthi/SaudiAddress/build-status/master)[![Quality Score](https://camo.githubusercontent.com/7214c9bef5f038dab9d534426ac7474506facee9ab339ef31124d79ea6ccec6b/68747470733a2f2f696d672e736869656c64732e696f2f7363727574696e697a65722f672f616c692d616c6861727468692f7361756469616464726573732e7376673f7374796c653d666c6174)](https://scrutinizer-ci.com/g/ali-alharthi/saudiaddress)[![Total Downloads](https://camo.githubusercontent.com/c4d8d7cc2e79cd87926eb64559907633783c9a06c39475703f5c6585d7ba3a70/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f616c692d616c6861727468692f7361756469616464726573732e7376673f7374796c653d666c6174)](https://packagist.org/packages/ali-alharthi/saudiaddress) SaudiAddress is a PHP package/library built to consume the Saudi National Address API ([api.address.gov.sa](api.address.gov.sa)). It makes it simple to use most of what the API has to offer. You can for example retrieve regions, cities, districts, services and addresses from geo coordinates, verify an address and more! Installation ------------ [](#installation) You can install the package via composer: ``` composer require ali-alharthi/saudiaddress ``` Laravel ------- [](#laravel) This package supports **Laravel** out of the box 😄. However, you need to add the following to the `config/services.php` file: ``` 'saudiaddress' => [ 'api_key' => env('SNA_API_KEY', null), 'api_subscription' => env('SNA_API_SUBSCRIPTION', 'Development'), 'cache' => env('SNA_CACHE', true), ], ``` Then, append the following to the `.env` file: ``` SNA_API_KEY=YOUR-API-KEY-HERE SNA_API_SUBSCRIPTION=Development SNA_CACHE=false ``` Replace `YOUR-API-KEY-HERE` with your SNA API key, `Development` with your SNA subscription type and `SNA_CACHE` with true or false (enable/disable cache). After that you can use the facade: `AliAlharthi\SaudiAddress\Facades\SaudiAddress` to access the library. Usage ----- [](#usage) ### As a regualr PHP package: [](#as-a-regualr-php-package) ``` use AliAlharthi\SaudiAddress\SaudiAddress; $saudi = SaudiAddress::make('API-KEY', 'Subscription', false); // Cache is disabled $regions = $saudi->regions()->all('E')->get(); ``` ### Laravel: [](#laravel-1) ``` use AliAlharthi\SaudiAddress\Facades\SaudiAddress; $regions = SaudiAddress::regions()->all('E')->get(); ``` --- ***In the following examples, parameter `'E'` stands for English. Default language is Arabic `'A'`*** --- ### 🔍 Short Address 🆕 [](#mag-short-address-new) - Get the full address using the Saudi short address: - parameter `short` is the "short address". ``` $addresses = $saudi->address()->shortAddress('short', 'E'); // return an array of address information ``` --- ### ✅ Verify a Short Address [](#white_check_mark-verify-a-short-address) - Verify a Short Address. - parameters `ECAB2823` and `RAHA3443` are the short addresses. ``` $verified = $saudi->address()->verifyShortAddress('ECAB2823', 'E'); // return true $verified = $saudi->address()->verifyShortAddress('RAHA3443', 'E'); // return false ``` ***Short address should consists of 4 letters followed by 4 numbers***`Example: ABCD1234` *An exception will be thrown if an incorrect short address was provided* --- ### 🌏 Regions [](#earth_asia-regions) - Get all regions: ``` $regions = $saudi->regions()->all('E')->get(); ``` - Get a region by ID: ``` $region = $saudi->regions()->all('E')->getId(2); ``` `getId()` aliases: `byId()` and `id()`. - Get a region by Name: ``` $region = $saudi->regions()->all('E')->getName('Dammam'); ``` `getName()` aliases: `byName()`, `name()` and `named()`. --- ### 🌏 Cities [](#earth_asia-cities) ***using `-1` as the region ID (on the `all()` method - before the language parameter) or leaving it empty will get all the cities of Saudi Arabia*** - Get all cities of Saudi Arabia: - parameter `-1` is the region ID. ``` $cities = $saudi->cities()->all(-1, 'E')->get(); ``` - Get all cities of a region ID: - parameter `3` is the region ID. ``` $cities = $saudi->cities()->all(3, 'E')->get(); ``` - Get a city by ID: ``` $city = $saudi->cities()->all(-1, 'E')->getId(2); ``` `getId()` aliases: `byId()` and `id()`. - Get a city by Name: ``` $city = $saudi->cities()->all(-1, 'E')->getName('Dammam'); ``` `getName()` aliases: `byName()`, `name()` and `named()`. - Get a city by Governorate Name: ``` $city = $saudi->cities()->all(-1, 'E')->getGov('Eastern Province'); ``` `getGov()` aliases: `byGovernorate()`, `byGov()` and `govName()`. --- ### 🌆 Districts [](#city_sunset-districts) - Get all districts from a city ID: - parameter `13` is the city ID. ``` $districts = $saudi->cities()->all(13, 'E')->get(); ``` - Get a district by ID: - parameter `13` is the city ID. ``` $district = $saudi->cities()->all(13, 'E')->getId(2); ``` `getId()` aliases: `byId()` and `id()`. - Get a district by Name: - parameter `13` is the city ID. ``` $district = $saudi->cities()->all(13, 'E')->getName('Dammam'); ``` `getName()` aliases: `byName()`, `name()` and `named()`. --- ### 🏪 Services [](#convenience_store-services) - Get the service categories: ``` $services = $saudi->services()->categories('E')->get(); ``` `categories()` aliases: `cat()` and `main()`. - Get the sub services of from a category ID: - parameter `102` is the service category ID. ``` $subServices = $saudi->services()->sub(102, 'E')->get(); ``` `sub()` aliases: `subCategories()` and `subServices()`. - Get a service category / sub service by ID: - parameter `102` is the service category ID. - parameter `10210` is the sub service ID. ``` $service = $saudi->cities()->categories('E')->getId(102); $subservice = $saudi->cities()->sub(102, 'E')->getId(10210); ``` `getId()` aliases: `byId()` and `id()`. - Get a service category / sub service by Name: - parameter `102` is the service category ID. ``` $service = $saudi->cities()->categories('E')->getName('Commercial'); $subservice = $saudi->cities()->sub(120, 'E')->getName('Supermarket'); ``` `getName()` aliases: `byName()`, `name()`, `serviceName()` and `named()`. --- ### 📍 GEO [](#round_pushpin-geo) - Address reverse (Get the address from geo coordinates): - parameter `24.65017630` is latitude and parameter `46.71670870` is longitude. ``` $address = $saudi->geo()->coordinates(24.65017630, 46.71670870, 'E')->get(); ``` `coordinates()` aliases: `coords()` and `location()`. - Get the city from geo: - parameter `24.65017630` represents latitude and parameter `46.71670870` represents longitude. ``` $city = $saudi->geo()->coordinates(24.65017630, 46.71670870, 'E')->getCity(); ``` `getCity()` aliases: `city()`. - Get the address line 1 from geo: - parameter `24.65017630` represents latitude and parameter `46.71670870` represents longitude. ``` $addressOne = $saudi->geo()->coordinates(24.65017630, 46.71670870, 'E')->getAddressOne(); ``` `getAddressOne()` aliases: `addressOne()`. - Get the address line 2 from geo: - parameter `24.65017630` represents latitude and parameter `46.71670870` represents longitude. ``` $addressTwo = $saudi->geo()->coordinates(24.65017630, 46.71670870, 'E')->getAddressTwo(); ``` `getAddressTwo()` aliases: `addressTwo()`. - Get the street name from geo: - parameter `24.65017630` represents latitude and parameter `46.71670870` represents longitude. ``` $street = $saudi->geo()->coordinates(24.65017630, 46.71670870, 'E')->getStreet(); ``` `getStreet()` aliases: `street()`. - Get the region from geo: - parameter `24.65017630` represents latitude and parameter `46.71670870` represents longitude. ``` $region = $saudi->geo()->coordinates(24.65017630, 46.71670870, 'E')->getRegion(); ``` `getRegion()` aliases: `region()`. - Get the district from geo: - parameter `24.65017630` represents latitude and parameter `46.71670870` represents longitude. ``` $district = $saudi->geo()->coordinates(24.65017630, 46.71670870, 'E')->getDistrict(); ``` `getDistrict()` aliases: `district()`. - Get the building number from geo: - parameter `24.65017630` represents latitude and parameter `46.71670870` represents longitude. ``` $buildingNumber = $saudi->geo()->coordinates(24.65017630, 46.71670870, 'E')->getBuildingNumber(); ``` `getBuildingNumber()` aliases: `buildingNumber()`. - Get the post code (zip) from geo: - parameter `24.65017630` represents latitude and parameter `46.71670870` represents longitude. ``` $postCode = $saudi->geo()->coordinates(24.65017630, 46.71670870, 'E')->getPostCode(); ``` `getPostCode()` aliases: `postCode()`, `getZip()` and `zip()`. - Get the additional number from geo: - parameter `24.65017630` represents latitude and parameter `46.71670870` represents longitude. ``` $additionalNumber = $saudi->geo()->coordinates(24.65017630, 46.71670870, 'E')->getAdditionalNumber(); ``` `getAdditionalNumber()` aliases: `additionalNumber()`. --- ### 🔍 Address Lookup [](#mag-address-lookup) - Find all the addresses using a string: - parameter `address string` is the "search string" and parameter `1` is the page #. ``` $addresses = $saudi->address()->find('address string', 1, 'E')->all(); // return a list of addresses ``` ***if page is set to `1` the package will loop through the pages and combine the results*** ***Developer Subscriptions will sleep for 5 seconds before fetching the next page!*** --- ### ✅ Verify an Address [](#white_check_mark-verify-an-address) - Verify an Address by building number, zip code and additional number. - parameters `8228` and `9999` are the building numbers. - parameters `12643` and `99999` are the zip codes. - parameters `2121` and `9999` are the additional numbers. ``` $verified = $saudi->address()->verify(8228, 12643, 2121, 'E'); // return true $verified = $saudi->address()->verify(9999, 99999, 9999, 'E'); // return false ``` --- 🔔 Other Information ------------------- [](#bell-other-information) This package was built by a single person within 2-3 days due to an actual need in a real-world project. This is still considered simple but gets the job done. Plus contributions ([CONTRIBUTING](CONTRIBUTING.md)) are welcomed 😁. **⚡ Cache** This package has a simple file cache system. Most of the API requests will be saved in the `Api/Cache/` directory due to the limitation on the Development subscription (1000 requests per month). *Redis and other cache methods will be added in the future versions* --- Contributing ------------ [](#contributing) Please see [CONTRIBUTING](CONTRIBUTING.md) for details. Security -------- [](#security) If you discover any security related issues, please email instead of using the issue tracker. Credits ------- [](#credits) - [Ali Alharthi](https://github.com/ali-alharthi) License ------- [](#license) The MIT License (MIT). Please see [License File](LICENSE.md) for more information. ### Health Score 28 — LowBetter than 54% of packages Maintenance19 Infrequent updates — may be unmaintained Popularity19 Limited adoption so far Community10 Small or concentrated contributor base Maturity52 Maturing project, gaining track record Bus Factor1 Top contributor holds 100% of commits — single point of failure How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Every ~207 days Total 3 Last Release 1669d ago Major Versions 1.3 → 2.02021-10-16 PHP version history (2 changes)1.2PHP >=5.5.9 2.0PHP >=7.2 ### Community Maintainers ![](https://avatars.githubusercontent.com/u/23663887?v=4)[Ali Alharthi](/maintainers/aalharthi)[@aalharthi](https://github.com/aalharthi) --- Top Contributors [![ali-alharthi](https://avatars.githubusercontent.com/u/29173253?v=4)](https://github.com/ali-alharthi "ali-alharthi (9 commits)") --- Tags phplaravelsaudiaddressali-alharthiSaudi National Address ### Code Quality TestsPHPUnit ### Embed Badge ![Health badge](/badges/ali-alharthi-saudiaddress/health.svg) ``` [![Health](https://phpackages.com/badges/ali-alharthi-saudiaddress/health.svg)](https://phpackages.com/packages/ali-alharthi-saudiaddress) ``` ### Alternatives [openai-php/laravel OpenAI PHP for Laravel is a supercharged PHP API client that allows you to interact with the Open AI API 3.7k7.6M74](/packages/openai-php-laravel)[mozex/anthropic-laravel Anthropic PHP for Laravel is a supercharged PHP API client that allows you to interact with the Anthropic API 71226.4k1](/packages/mozex-anthropic-laravel)[scriptdevelop/whatsapp-manager Paquete para manejo de WhatsApp Business API en Laravel 762.6k](/packages/scriptdevelop-whatsapp-manager)[dariusiii/tmdb-laravel Laravel Package for TMDB ( The Movie Database ) API. Provides easy access to the wtfzdotnet/php-tmdb-api library. 1821.1k](/packages/dariusiii-tmdb-laravel)[madeitbelgium/wordpress-php-sdk WordPress Laravel PHP SDK 4422.9k1](/packages/madeitbelgium-wordpress-php-sdk)[jeroen-g/flickr Modern PHP package to make Flickr API calls. Ships with Laravel implementation. 2559.9k2](/packages/jeroen-g-flickr) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)