README

用于在美国和加拿大进行正向和反向地址地理编码的库。

安装
使用方法
与 Laravel 一起使用
测试
变更日志
安全性
许可证

安装

您可以通过 composer 安装此包

composer require geocodio/geocodio-library-php

使用 Laravel？太好了！有一个可选的 Laravel 服务提供程序，可以轻松将其集成到您的应用程序中。

使用方法

还没有 API 密钥？在 https://dash.geocod.io 上注册以获取 API 密钥。每天前 2,500 次查找是免费的。

单个地理编码

使用 Laravel 集成？请查看下面的 Laravel 特定使用示例。

$geocoder = new Geocodio\Geocodio();
$geocoder->setApiKey('YOUR_API_KEY');
// $geocoder->setHostname('api-hipaa.geocod.io'); // optionally overwrite the API hostname

$response = $geocoder->geocode('1109 N Highland St, Arlington, VA');
dump($response);
/*
array:2 [
  "input" => array:2 [
    "address_components" => array:8 [
      "number" => "1109"
      "predirectional" => "N"
      "street" => "Highland"
      "suffix" => "St"
      "formatted_street" => "N Highland St"
      "city" => "Arlington"
      "state" => "VA"
      "country" => "US"
    ]
    "formatted_address" => "1109 N Highland St, Arlington, VA"
  ]
  "results" => array:1 [
    0 => array:6 [
      "address_components" => array:10 [
        "number" => "1109"
        "predirectional" => "N"
        "street" => "Highland"
        "suffix" => "St"
        "formatted_street" => "N Highland St"
        "city" => "Arlington"
        "county" => "Arlington County"
        "state" => "VA"
        "zip" => "22201"
        "country" => "US"
      ]
      "formatted_address" => "1109 N Highland St, Arlington, VA 22201"
      "location" => array:2 [
        "lat" => 38.886672
        "lng" => -77.094735
      ]
      "accuracy" => 1
      "accuracy_type" => "rooftop"
      "source" => "Arlington"
    ]
  ]
]
*/

$response = $geocoder->reverse('38.9002898,-76.9990361');
$response = $geocoder->reverse([38.9002898, -76.9990361]);

注意：您可以在 https://www.geocod.io/docs/ 上阅读有关精度分数、精度类型、输入格式等内容。

批量地理编码

要批量地理编码，只需传递一个地址或坐标数组，而不是单个字符串。

$response = $geocoder->geocode([
    '1109 N Highland St, Arlington VA',
    '525 University Ave, Toronto, ON, Canada',
    '4410 S Highway 17 92, Casselberry FL',
    '15000 NE 24th Street, Redmond WA',
    '17015 Walnut Grove Drive, Morgan Hill CA'
]);

$response = $geocoder->reverse([
    '35.9746000,-77.9658000',
    '32.8793700,-96.6303900',
    '33.8337100,-117.8362320',
    '35.4171240,-80.6784760'
]);

// Optionally supply a custom key that will be returned along with results
$response = $geocoder->geocode([
    'MyId1' => '1109 N Highland St, Arlington VA',
    'MyId2' => '525 University Ave, Toronto, ON, Canada',
    'MyId3' => '4410 S Highway 17 92, Casselberry FL',
    'MyId4' => '15000 NE 24th Street, Redmond WA',
    'MyId5' => '17015 Walnut Grove Drive, Morgan Hill CA'
]);

字段追加

Geocodio 允许您追加额外的数据点，例如国会选区、普查代码、时区、ACS 调查结果等。

要请求额外的字段，只需将它们作为数组作为第二个参数提供。

$response = $geocoder->geocode(
    [
        '1109 N Highland St, Arlington VA',
        '525 University Ave, Toronto, ON, Canada'
    ],
    [
        'cd',
        'timezone'
    ]
);

$response = $geocoder->reverse('38.9002898,-76.9990361', ['census2010']);

地址组件

对于正向地理编码请求，您可以提供单个地址组件而不是完整的地址字符串。这对单个和批量地理编码请求都适用。

$response = $geocoder->geocode([
    'street' => '1109 N Highland St',
    'city' => 'Arlington',
    'state' => 'VA',
    'postal_code' => '22201'
]);

$response = $geocoder->geocode([
    [
        'street' => '1109 N Highland St',
        'city' => 'Arlington',
        'state' => 'VA'
    ],
    [
        'street' => '525 University Ave',
        'city' => 'Toronto',
        'state' => 'ON',
        'country' => 'Canada',
    ],
);

限制结果

可选地，您可以使用 geocode(...) 或 reverse(...) 上的第三个参数来限制最大地理编码结果数。

$response = $geocoder->geocode('1109 N Highland St, Arlington, VA', [], 1); // Only get the first result
$response = $geocoder->reverse('38.9002898,-76.9990361', ['timezone'], 5); // Return up to 5 geocoding results

上传列表

列表 API 允许您上传和处理包含地址或坐标的工作表。类似于仪表板中的工作表功能，工作表将作为 Geocodio 基础设施上的作业进行处理，可以在稍后时间下载。当工作表正在处理时，可以查询状态和进度。

重要

通过列表 API 处理的工作表数据将在完成处理 72 小时后自动删除。除了 1GB 的文件大小限制外，我们建议每个列表批次最多查找 10M。较大的批次应拆分为多个列表作业。

有关地理编码列表的详细信息，请参阅 API 文档。

从文件上传列表

创建一个新的工作表列表作业，并在后台开始处理列表。响应返回一个列表 ID，可以用来检索作业进度以及完成时下载已处理列表。

$response = $geocoder->uploadList(
    file: 'path/to/file.csv',
    direction: GeocodeDirection::Forward,
    format: '{{B}} {{C}} {{D}} {{E}}',
    callbackWebhook: 'https://example.com/callbacks/list-upload',
);

/*
array:2 [
  "id" => 11953719
  "file" => array:3 [
    "headers" => array:5 [
      0 => "Name"
      1 => "Address"
      2 => "City"
      3 => "State"
      4 => "Zip"
    ]
    "estimated_rows_count" => 4
    "filename" => "simple.csv"
  ]
]
*/

上传内联数据列表

$csvData = <<<'CSV'
name,street,city,state,zip
"Peregrine Espresso","660 Pennsylvania Ave SE",Washington,DC,20003
"Lot 38 Espresso Bar","1001 2nd St SE",Washington,DC,20003
CSV;

$geocodio->uploadInlineList(
    $csvData,
    'coffee-shops.csv',
    GeocodeDirection::Forward,
    '{{B}} {{C}} {{D}} {{E}}'
);

列表状态

查看单个上传列表的元数据和状态。

$geocoder->listStatus(11950669);

/*
array:6 [
  "id" => 11953719
  "fields" => []
  "file" => array:2 [
    "estimated_rows_count" => 4
    "filename" => "simple.csv"
  ]
  "status" => array:5 [
    "state" => "COMPLETED"
    "progress" => 100
    "message" => "Completed"
    "time_left_description" => null
    "time_left_seconds" => null
  ]
  "download_url" => "https://api.geocod.io/v1.7/lists/11953719/download"
  "expires_at" => "2024-09-22T20:36:10.000000Z"
]
*/

下载列表

下载一个完全地理编码的列表，返回的格式始终是UTF-8编码的逗号分隔的csv文件。

$geocoder->downloadList(11950669, 'path/to/file.csv');

获取所有上传列表

显示所有创建的列表。端点是分页的，每次显示15个列表，按时间顺序排列。

$geocoder->lists();

/*
array:9 [
  "current_page" => 1
  "data" => array:1 [
    0 => array:6 [
      "id" => 11953719
      "fields" => []
      "file" => array:2 [
        "estimated_rows_count" => 4
        "filename" => "simple.csv"
      ]
      "status" => array:5 [
        "state" => "COMPLETED"
        "progress" => 100
        "message" => "Completed"
        "time_left_description" => null
        "time_left_seconds" => null
      ]
      "download_url" => "https://api.geocod.io/v1.7/lists/11953719/download"
      "expires_at" => "2024-09-22T20:36:10.000000Z"
    ]
  "first_page_url" => "https://api.geocod.io/v1.7/lists?page=1"
  "from" => 1
  "next_page_url" => null
  "path" => "https://api.geocod.io/v1.7/lists"
  "per_page" => 15
  "prev_page_url" => null
  "to" => 3
]
*/

删除上传列表

永久删除之前上传的列表及其底层电子表格数据。这也可以用来取消和删除当前正在处理的电子表格。

Geocodio无限用户可以随时取消电子表格。按需付费用户只有在电子表格刚刚开始时才能取消。

如果未手动删除，则电子表格数据将在72小时后自动删除。

$geocoder->deleteList(11950669);

与 Laravel 一起使用

此库在不使用Laravel的情况下也能很好地工作，但如果您恰好在使用Laravel，您可以享受一些Laravel特定的功能。

较新的Laravel版本将自动发现此包，因此您只需发布配置文件即可。

php artisan vendor:publish --provider="Geocodio\GeocodioServiceProvider"

现在您可以在 config/geocodio.php 中编辑您的配置文件。

现在您可以使用 Geocodio 门面，或者依赖注入完全配置的 Geocodio 类。

// Using facade
use Geocodio;

$response = Geocodio::geocode('1109 N Highland St, Arlington, VA');

// Using dependency injection
use Geocodio\Geocodio;

class SomeController {
  public function __construct(Geocodio $geocoder) {
      $response = $geocoder->geocode('1109 N Highland St, Arlington, VA');
  }
}

测试

$ composer test

变更日志

有关最近更改的更多信息，请参阅变更日志。

安全性

如果您发现任何安全问题，请通过security@geocod.io 发送电子邮件，而不是使用问题跟踪器。

许可证

MIT许可（MIT）。有关更多信息，请参阅许可文件。

geocodio / geocodio-library-php

维护者

详细信息