README

Postcodes.io 的简单 PHP SDK Postcodes.io

安装

使用 composer 安装

$ composer require ammaar23/postcodes-io-sdk

文档

基本使用示例

use Ammaar23\Postcodes\Postcode;
use Ammaar23\Postcodes\PostcodeException;

try {
    $postcodeService = new Postcode();
    $response = $postcodeService->lookup('M60 2LA');
    echo $response->admin_district;
} catch(PostcodeException $e) {
    echo $e->getMessage();
} catch(\Exception $e) {
    echo $e->getMessage();
}

您可以捕获特定的 Ammaar23\Postcodes\PostcodeException 和/或捕获一般的 \Exception 以捕获任何类型。

添加/修改配置参数

您可以查看 Guzzle HTTP 请求选项以找到可用的选项。

$postcodeService = new Postcode([
    'headers' => [
        'User-Agent' => 'testing/1.0',
        'Accept' => 'application/json'
    ],
    'timeout' => 2.0
]);

方法

查找邮编

对于给定的邮编返回单个邮编实体（不区分大小写和空格）。

// Definition
function lookup(string $postcode): stdClass;

// Example
$postcodeService->lookup('M60 2LA');

批量查找邮编

返回匹配的邮编及其相应可用数据的列表。

// Definition
function lookupBulk(array $postcodes, array $attributes = []): array;

// Examples
$postcodeService->lookupBulk(['OX49 5NU', 'NE30 1DP']);
$postcodeService->lookupBulk(
    ['OX49 5NU', 'NE30 1DP'],
    ['postcode', 'longitude', 'latitude']
);

$attributes（非必需）是返回到结果对象（的）数组属性。

反向地理编码

对于给定的经纬度返回最近的邮编。

// Definition
function reverseGeocode(float $latitude, float $longitude, array $options = []): array;

// Examples
$postcodeService->reverseGeocode(51.7923246977375, 0.629834723775309);
$postcodeService->reverseGeocode(51.7923246977375, 0.629834723775309, [
    'limit' => 5,
    'radius' => 1000
]);

limit（非必需）限制返回的邮编匹配数。默认为 10。需要小于 100。
radius（非必需）限制返回的邮编匹配数。默认为 100m。需要小于 2,000m。

批量反向地理编码

批量将地理位置转换为邮编。

// Definition
function reverseGeocodeBulk(array $geolocations, array $attributes = [], int $wideSearch = null): array;

// Examples
$postcodeService->reverseGeocodeBulk([
    ['latitude' => 51.7923246977375, 'longitude' => 0.629834723775309],
    ['latitude' => 53.5351312861402, 'longitude' => -2.49690382054704, 'radius' => 1000, 'limit' => 5]
]);
$postcodeService->reverseGeocodeBulk([
    ['latitude' => 51.7923246977375, 'longitude' => 0.629834723775309],
    ['latitude' => 53.5351312861402, 'longitude' => -2.49690382054704, 'radius' => 1000, 'limit' => 5]
], ['postcode', 'longitude', 'latitude']);
$postcodeService->reverseGeocodeBulk([
    ['latitude' => 51.7923246977375, 'longitude' => 0.629834723775309],
    ['latitude' => 53.5351312861402, 'longitude' => -2.49690382054704, 'radius' => 1000, 'limit' => 5]
], ['postcode', 'longitude', 'latitude'], 1000);

每个请求最多 100 个地理位置。
$attributes（非必需）是返回到结果对象（的）数组属性。
$wideSearch（非必需）搜索半径最多 20km，但结果最多为 10 个。

随机邮编

返回随机邮编及其所有可用数据。

// Definition
function random(array $options = []): stdClass;

// Examples
$postcodeService->random();
$postcodeService->random([
    'outcode' => 'M60'
]);

outcode（非必需）按出码过滤随机邮编。如果出码无效，则返回 null。

验证邮编

验证邮编的便利方法。

// Definition
function validate(string $postcode): bool;

// Example
$postcodeService->validate('M60 2LA');

验证邮编格式

验证邮编格式的便利方法。

// Definition
function validateFormat(string $postcode): bool;

// Example
$postcodeService->validateFormat('M60 2LA');

validateFormat 仅验证格式，而 validate 检查它是否存在于 Postcodes.io 数据库中。

邮编的最近邮编

对于给定的邮编返回最近的邮编。

// Definition
function nearest(string $postcode, array $options = []): array;

// Examples
$postcodeService->nearest('M60 2LA');
$postcodeService->nearest('M60 2LA', [
    'limit' => 5,
    'radius' => 1000
]);

limit（非必需）限制返回的邮编匹配数。默认为 10。需要小于 100。
radius（非必需）限制返回的邮编匹配数。默认为 100m。需要小于 2,000m。

自动完成邮编部分

返回匹配邮编的便利方法。

// Definition
function autocomplete(string $postcode, array $options = []): array;

// Examples
$postcodeService->autocomplete('M60');
$postcodeService->autocomplete('M60', ['limit' => 5]);

limit（非必需）限制返回的邮编匹配数。默认为 10。需要小于 100。

查询邮编

提交邮编查询并接收邮编匹配的完整列表及其所有相关邮编数据。结果集可以为空，也可以包含最多 100 个邮编实体。

// Definition
function query(string $query, array $options = []): array|null;

// Examples
$postcodeService->query('M60 2LA');
$postcodeService->query('M60 2LA', ['limit' => 5]);

limit（非必需）限制返回的邮编匹配数。默认为 10。需要小于 100。

测试

$ composer test

与覆盖率 OR

$ composer test-coverage

ammaar23 / postcodes-io-sdk

维护者

详细信息