PHPackages naif/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. naif/saudiaddress ActiveLibrary[API Development](/categories/api) naif/saudiaddress ================= Laravel wrapper for the Saudi National Address APIs v2.1.0(4mo ago)19472MITPHPPHP >=7.2 Since Jul 31Pushed 4mo agoCompare [ Source](https://github.com/naifalshaye/saudiaddress)[ Packagist](https://packagist.org/packages/naif/saudiaddress)[ RSS](/packages/naif-saudiaddress/feed)WikiDiscussions master Synced 2w ago READMEChangelogDependencies (5)Versions (3)Used By (0) Saudi Address - Laravel Package =============================== [](#saudi-address---laravel-package) Laravel wrapper for the [Saudi National Address APIs](https://api.address.gov.sa/). Requirements ------------ [](#requirements) - PHP >= 7.2 - Laravel 5.5 - 12.x Installation ------------ [](#installation) ``` composer require naif/saudiaddress ``` **Laravel 5.5+** uses auto-discovery, so the service provider and facade are registered automatically. For **Laravel < 5.5**, add to `config/app.php`: ``` 'providers' => [ Naif\Saudiaddress\SaudiAddressServiceProvider::class, ], 'aliases' => [ 'SaudiAddress' => Naif\Saudiaddress\Facades\SaudiAddress::class, ], ``` Configuration ------------- [](#configuration) ### API Key [](#api-key) Get your API key from and add it to your `.env`: ``` SAUDI_ADDRESS_API_KEY=your-api-key-here ``` The default API URL is already configured. Override it only if needed: ``` SAUDI_ADDRESS_API_URL=https://apina.address.gov.sa/NationalAddress/v3.1 ``` ### Optional Settings [](#optional-settings) ``` SAUDI_ADDRESS_LANGUAGE=A # Default language: A (Arabic) or E (English) SAUDI_ADDRESS_TIMEOUT=30 # HTTP timeout in seconds ``` ### Publish Config [](#publish-config) To customize the configuration file: ``` php artisan vendor:publish --tag=saudiaddress-config ``` Usage ----- [](#usage) ### Get Regions [](#get-regions) ``` use Naif\Saudiaddress\Facades\SaudiAddress; $regions = SaudiAddress::regions(); // In English $regions = SaudiAddress::regions('E'); ``` ### Get Cities [](#get-cities) ``` // All cities $cities = SaudiAddress::cities(); // Cities in a specific region $cities = SaudiAddress::cities(1); // In English $cities = SaudiAddress::cities(1, 'E'); ``` ### Get Districts [](#get-districts) ``` // Districts within a city $districts = SaudiAddress::districts(3); // In English $districts = SaudiAddress::districts(3, 'E'); ``` ### Reverse Geocode [](#reverse-geocode) Get address details from latitude/longitude coordinates: ``` $address = SaudiAddress::geoCode(24.774265, 46.738586); // Access properties echo $address->BuildingNumber; // "7596" echo $address->Street; // "الديوان" echo $address->District; // "Al Hamra Dist.,حي الحمراء" echo $address->City; // "RIYADH,الرياض" echo $address->PostCode; // "13216" ``` ### Verify Address [](#verify-address) Verify an address by building number, postal code, and additional number: ``` $isValid = SaudiAddress::verify(7596, 13216, 2802); if ($isValid) { echo 'Address is valid!'; } ``` ### Free-Text Address Search [](#free-text-address-search) Search for addresses using free-text query: ``` $addresses = SaudiAddress::freeTextSearch('Riyadh Olaya'); // With pagination (10 results per page) $addresses = SaudiAddress::freeTextSearch('Riyadh Olaya', 2); // In English $addresses = SaudiAddress::freeTextSearch('Riyadh Olaya', 1, 'E'); ``` ### Fixed-Parameter Address Search [](#fixed-parameter-address-search) Search for addresses using specific parameters: ``` $addresses = SaudiAddress::fixedSearch([ 'CityId' => 3, 'DistrictId' => 100, 'StreetName' => 'King Fahd', ]); // With pagination $addresses = SaudiAddress::fixedSearch(['CityId' => 3], 2); ``` ### Bulk Address Search [](#bulk-address-search) Search for multiple addresses at once (up to 10): ``` $addresses = SaudiAddress::bulkSearch([ 'Riyadh, Olaya, 1234', 'Jeddah, Al Hamra, 5678', ]); ``` ### Short Address Lookup [](#short-address-lookup) Look up a national address by short address code (4 letters + 4 digits): ``` $addresses = SaudiAddress::shortAddress('ABCD1234'); ``` ### Verify Short Address [](#verify-short-address) Check whether a short address code is valid: ``` $isValid = SaudiAddress::verifyShortAddress('ABCD1234'); if ($isValid) { echo 'Short address is valid!'; } ``` ### POI Free-Text Search [](#poi-free-text-search) Search for points of interest using free text: ``` $results = SaudiAddress::poiFreeTextSearch('hospital'); // With pagination $results = SaudiAddress::poiFreeTextSearch('hospital', 2); ``` ### POI Fixed-Parameter Search [](#poi-fixed-parameter-search) Search for points of interest with specific parameters: ``` $results = SaudiAddress::poiFixedSearch('school', 1); // With optional filters $results = SaudiAddress::poiFixedSearch('school', 1, ['CityId' => 3]); ``` ### Nearest POI [](#nearest-poi) Find nearest points of interest by coordinates: ``` $results = SaudiAddress::nearestPoi(24.774265, 46.738586); // With custom radius (km) $results = SaudiAddress::nearestPoi(24.774265, 46.738586, 2.0); ``` ### Service Categories [](#service-categories) Get service categories for POI search: ``` $categories = SaudiAddress::serviceCategories(); // In English $categories = SaudiAddress::serviceCategories('E'); ``` ### Service Sub-Categories [](#service-sub-categories) Get sub-categories for a given service category: ``` $subCategories = SaudiAddress::serviceSubCategories(1); ``` ### Send OTP (Address By Phone) [](#send-otp-address-by-phone) Send OTP to a mobile number for address lookup: ``` $response = SaudiAddress::sendOtp('STORE001', '0501234567'); ``` ### Address By Phone [](#address-by-phone) Get addresses associated with a phone number after OTP verification: ``` $addresses = SaudiAddress::addressByPhone('STORE001', '0501234567', '1234'); ``` ### Feature Extents [](#feature-extents) Get geographic extents for a feature layer: ``` // Valid layers: regions, cities, districts, streets, zipcodes $extents = SaudiAddress::featureExtents('regions', '1'); echo $extents->xmin; echo $extents->ymin; echo $extents->xmax; echo $extents->ymax; ``` Error Handling -------------- [](#error-handling) All methods throw typed exceptions that extend `SaudiAddressException`: ``` use Naif\Saudiaddress\Exceptions\SaudiAddressException; use Naif\Saudiaddress\Exceptions\ApiRequestException; use Naif\Saudiaddress\Exceptions\InvalidResponseException; use Naif\Saudiaddress\Exceptions\AddressNotFoundException; use Naif\Saudiaddress\Exceptions\InvalidConfigurationException; try { $address = SaudiAddress::geoCode(24.774265, 46.738586); } catch (AddressNotFoundException $e) { // No address found at these coordinates } catch (ApiRequestException $e) { // Network error or API returned an error } catch (InvalidResponseException $e) { // API returned unexpected data } catch (SaudiAddressException $e) { // Catch-all for any Saudi Address related error } ``` Testing ------- [](#testing) ``` composer test ``` Support ------- [](#support) - Author: Naif Alshaye () - LinkedIn: License ------- [](#license) The MIT License (MIT). Please see [License File](LICENSE) for more information. ### Health Score 43 — FairBetter than 90% of packages Maintenance75 Regular maintenance activity Popularity17 Limited adoption so far Community10 Small or concentrated contributor base Maturity59 Maturing project, gaining track record Bus Factor1 Top contributor holds 70.4% 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 Unknown Total 1 Last Release 138d ago ### Community Maintainers ![](https://www.gravatar.com/avatar/323a5cbb1087ce4edc9deec40b03736b6d43a3ca205615b346108ed57f58e50e?d=identicon)[naifdev](/maintainers/naifdev) --- Top Contributors [![naifalshaye](https://avatars.githubusercontent.com/u/23122187?v=4)](https://github.com/naifalshaye "naifalshaye (19 commits)")[![naifdev](https://avatars.githubusercontent.com/u/17527496?v=4)](https://github.com/naifdev "naifdev (8 commits)") --- Tags addressbuldingcititesdistrictslaravellaravel-packagelookupnationalnational-addresspostcodesaudisaudi-addressverifyzipcodephplaraveladdressaddressessaudi-arabiasaudisaudiaddressnational-address ### Code Quality TestsPHPUnit ### Embed Badge ![Health badge](/badges/naif-saudiaddress/health.svg) ``` [![Health](https://phpackages.com/badges/naif-saudiaddress/health.svg)](https://phpackages.com/packages/naif-saudiaddress) ``` ### Alternatives [simplestats-io/laravel-client Analytics for Laravel. Track visitors, registrations, and payments. Discover which channels actually drive revenue, not just traffic. Server-side, GDPR compliant, ad-blocker proof. 5019.3k](/packages/simplestats-io-laravel-client)[smodav/mpesa M-Pesa API implementation 16167.1k1](/packages/smodav-mpesa) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)