Saudi National Address API

SaudiAddress is a PHP package/library built to consume the Saudi National Address API (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

You can install the package via composer:

composer require ali-alharthi/saudiaddress

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

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:

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 🆕

• 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

• 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

• 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

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

• 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

• 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

• 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

• 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

• 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

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) 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

Please see CONTRIBUTING for details.

Security

If you discover any security related issues, please email [email protected] instead of using the issue tracker.

Credits

• Ali Alharthi

License

The MIT License (MIT). Please see License File for more information.