README

SaudiAddress 是一个用于消费沙特国家地址 API (api.address.gov.sa) 的 PHP 包/库。它使得使用 API 提供的大部分功能变得简单。

例如，您可以检索地区、城市、地区、服务和地址，从地理坐标获取地址，验证地址等！

安装

您可以通过 composer 安装此包

composer require ali-alharthi/saudiaddress

Laravel

此包支持 Laravel，无需额外设置 😄。

但是，您需要将以下内容添加到 config/services.php 文件中

'saudiaddress' => [
    'api_key' => env('SNA_API_KEY', null),
    'api_subscription' =>
    env('SNA_API_SUBSCRIPTION', 'Development'),
    'cache' => env('SNA_CACHE', true),
],

然后，将以下内容追加到 .env 文件中

SNA_API_KEY=YOUR-API-KEY-HERE
SNA_API_SUBSCRIPTION=Development
SNA_CACHE=false

将 YOUR-API-KEY-HERE 替换为您的 SNA API 密钥，Development 替换为您的 SNA 订阅类型，将 SNA_CACHE 替换为 true 或 false（启用/禁用缓存）。

之后，您可以使用外观： AliAlharthi\SaudiAddress\Facades\SaudiAddress 来访问库。

用法

作为常规 PHP 包

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

在以下示例中，参数 'E' 表示英文。默认语言为阿拉伯语 'A'

🔍 短地址 🆕

• 使用沙特短地址获取完整地址
  • 参数 short 是“短地址”。

$addresses = $saudi->address()->shortAddress('short', 'E'); // return an array of address information

✅ 验证短地址

• 验证短地址。
  • 参数 ECAB2823 和 RAHA3443 是短地址。

$verified = $saudi->address()->verifyShortAddress('ECAB2823', 'E'); // return true
$verified = $saudi->address()->verifyShortAddress('RAHA3443', 'E'); // return false

短地址应包含 4 个字母后跟 4 个数字 示例：ABCD1234

如果提供了不正确的短地址，将抛出异常

🌏 地区

• 获取所有地区

$regions = $saudi->regions()->all('E')->get();

• 通过 ID 获取地区

$region = $saudi->regions()->all('E')->getId(2);

getId() 别名： byId() 和 id()。

• 通过名称获取地区

$region = $saudi->regions()->all('E')->getName('Dammam');

getName() 别名： byName()、name() 和 named()。

🌏 城市

使用 -1 作为地区 ID（在 all() 方法中 - 在语言参数之前）或留空将获取沙特阿拉伯的所有城市

• 获取沙特阿拉伯的所有城市
  • 参数 -1 是地区 ID。

$cities = $saudi->cities()->all(-1, 'E')->get();

• 获取具有特定地区 ID 的所有城市
  • 参数 3 是地区 ID。

$cities = $saudi->cities()->all(3, 'E')->get();

• 通过 ID 获取城市

$city = $saudi->cities()->all(-1, 'E')->getId(2);

getId() 别名： byId() 和 id()。

• 通过名称获取城市

$city = $saudi->cities()->all(-1, 'E')->getName('Dammam');

getName() 别名： byName()、name() 和 named()。

• 通过省名称获取城市

$city = $saudi->cities()->all(-1, 'E')->getGov('Eastern Province');

getGov() 别名： byGovernorate()、byGov() 和 govName()。

🌆 地区

• 从城市 ID 获取所有地区
  • 参数 13 是城市 ID。

$districts = $saudi->cities()->all(13, 'E')->get();

• 通过 ID 获取地区
  • 参数 13 是城市 ID。

$district = $saudi->cities()->all(13, 'E')->getId(2);

getId() 别名： byId() 和 id()。

• 通过名称获取地区
  • 参数 13 是城市 ID。

$district = $saudi->cities()->all(13, 'E')->getName('Dammam');

getName() 别名： byName()、name() 和 named()。

🏪 服务

• 获取服务类别

$services = $saudi->services()->categories('E')->get();

categories() 别名： cat() 和 main()。

• 获取特定类别 ID 的子服务
  • 参数 102 是服务类别 ID。

$subServices = $saudi->services()->sub(102, 'E')->get();

sub() 别名： subCategories() 和 subServices()。

• 通过 ID 获取服务类别/子服务
  • 参数 102 是服务类别 ID。
  • 参数 10210 是子服务 ID。

$service = $saudi->cities()->categories('E')->getId(102);
$subservice = $saudi->cities()->sub(102, 'E')->getId(10210);

getId() 别名： byId() 和 id()。

• 通过名称获取服务类别/子服务
  • 参数 102 是服务类别 ID。

$service = $saudi->cities()->categories('E')->getName('Commercial');
$subservice = $saudi->cities()->sub(120, 'E')->getName('Supermarket');

getName() 别名： byName()、name()、serviceName() 和 named()。

📍 GEO

• 地址反向（从地理坐标获取地址）
  • 参数 24.65017630 是纬度，参数 46.71670870 是经度。

$address = $saudi->geo()->coordinates(24.65017630, 46.71670870, 'E')->get();

coordinates() 的别名：coords() 和 location()。

• 从地理信息中获取城市
  • 参数 24.65017630 表示纬度，参数 46.71670870 表示经度。

$city = $saudi->geo()->coordinates(24.65017630, 46.71670870, 'E')->getCity();

getCity() 的别名：city()。

• 从地理信息中获取地址行1
  • 参数 24.65017630 表示纬度，参数 46.71670870 表示经度。

$addressOne = $saudi->geo()->coordinates(24.65017630, 46.71670870, 'E')->getAddressOne();

getAddressOne() 的别名：addressOne()。

• 从地理信息中获取地址行2
  • 参数 24.65017630 表示纬度，参数 46.71670870 表示经度。

$addressTwo = $saudi->geo()->coordinates(24.65017630, 46.71670870, 'E')->getAddressTwo();

getAddressTwo() 的别名：addressTwo()。

• 从地理信息中获取街道名称
  • 参数 24.65017630 表示纬度，参数 46.71670870 表示经度。

$street = $saudi->geo()->coordinates(24.65017630, 46.71670870, 'E')->getStreet();

getStreet() 的别名：street()。

• 从地理信息中获取区域
  • 参数 24.65017630 表示纬度，参数 46.71670870 表示经度。

$region = $saudi->geo()->coordinates(24.65017630, 46.71670870, 'E')->getRegion();

getRegion() 的别名：region()。

• 从地理信息中获取区
  • 参数 24.65017630 表示纬度，参数 46.71670870 表示经度。

$district = $saudi->geo()->coordinates(24.65017630, 46.71670870, 'E')->getDistrict();

getDistrict() 的别名：district()。

• 从地理信息中获取建筑物号
  • 参数 24.65017630 表示纬度，参数 46.71670870 表示经度。

$buildingNumber = $saudi->geo()->coordinates(24.65017630, 46.71670870, 'E')->getBuildingNumber();

getBuildingNumber() 的别名：buildingNumber()。

• 从地理信息中获取邮政编码（邮编）
  • 参数 24.65017630 表示纬度，参数 46.71670870 表示经度。

$postCode = $saudi->geo()->coordinates(24.65017630, 46.71670870, 'E')->getPostCode();

getPostCode() 的别名：postCode()、getZip() 和 zip()。

• 从地理信息中获取附加数字
  • 参数 24.65017630 表示纬度，参数 46.71670870 表示经度。

$additionalNumber = $saudi->geo()->coordinates(24.65017630, 46.71670870, 'E')->getAdditionalNumber();

getAdditionalNumber() 的别名：additionalNumber()。

🔍 地址查找

• 使用字符串查找所有地址
  • 参数 address string 是“搜索字符串”，参数 1 是页码。

$addresses = $saudi->address()->find('address string', 1, 'E')->all(); // return a list of addresses

如果页码设置为 1，则包将循环遍历页面并合并结果

开发者订阅将在获取下一页之前暂停5秒！

✅ 验证地址

• 通过建筑物号、邮编和附加数字验证地址。
  • 参数 8228 和 9999 是建筑物号。
  • 参数 12643 和 99999 是邮编。
  • 参数 2121 和 9999 是附加数字。

$verified = $saudi->address()->verify(8228, 12643, 2121, 'E'); // return true
$verified = $saudi->address()->verify(9999, 99999, 9999, 'E'); // return false

🔔 其他信息

由于在真实世界项目中实际需要，此包由一个人在2-3天内构建。

这仍然被认为是简单的，但可以完成工作。此外，欢迎贡献（CONTRIBUTING）😁。

⚡ 缓存

此包有一个简单的文件缓存系统。由于开发订阅的限制（每月1000次请求），大多数API请求将保存在 Api/Cache/ 目录中。

将在未来版本中添加Redis和其他缓存方法。

贡献

请参阅 CONTRIBUTING 了解详细信息。

安全

如果您发现任何与安全相关的问题，请通过电子邮件 ali@aalharthi.sa 而不是使用问题跟踪器。

鸣谢

• Ali Alharthi

许可

MIT许可（MIT）。请参阅 许可文件 了解更多信息。