README

构建状态:

WSI-Services SmartyStreetsAPI

用于解析和验证街道地址的 PHP 库，针对 SmartyStreets API。需要 SmartyStreets 的 API ID 和令牌才能使用此库。您可以通过 SmartyStreets 账户创建账户并通过生成密钥来获取 API 密钥。

关于 SmartyStreets

SmartyStreets 提供地址地理编码解析和验证、城市、州、邮编匹配、地址自动完成和地址提取。提供免费和商业账户。

地址验证提供许多好处 - 减少退回的邮件、更好的地址数据、合并重复地址、改善与客户的沟通、降低邮寄成本、减少处理不良数据的时间，并提高投递速度。SmartyStreets 给您所有这些，甚至更多。

安装 SmartyStreetsAPI

GIT

在本地克隆 GIT 存储库

$ git clone https://github.com/WSI-Services/SmartyStreetsAPI.git

Composer

从命令行将库添加到您的 Composer 依赖项

$ composer require wsiservices/smartystreetsapi

或者

将所需部分添加到您的 composer.json 文件中

"require": {
	"wsiservices/smartystreetsapi": "1.*"
}

依赖

安装系统依赖项

apt-get -y install php5-dev libcurl3 libmagic1 zlib1g-dev

安装 PECL 依赖项 'raphf'

pecl install raphf

创建 PECL 'raphf' 配置文件：/etc/php5/mods-available/raphf.ini

; configuration for php raphf module
; priority=20
extension=raphf.so

启用 PHP 模块 'raphf'

php5enmod raphf

安装 PECL 依赖项 'propro'

pecl install propro

创建 PECL 'propro' 配置文件：/etc/php5/mods-available/propro.ini

; configuration for php propro module
; priority=30
extension=propro.so

启用 PHP 模块 'propro'

php5enmod propro

要定位已安装的库路径，将 {LIBRARY} 替换为 libz，

libcurl，libevent.* 和 libidn

ldconfig -p | grep "{LIBRARY}.so" | awk '{print $4}' | head -n1

安装 PECL 依赖项 'pecl_http'

pecl install pecl_http

使用找到的库路径回答以下问题

where to find zlib [/usr] :
where to find libcurl [/usr] :
where to find libevent [/usr] :
where to find libidn [/usr] :

创建 PECL 'http' 配置文件：/etc/php5/mods-available/http.ini

; configuration for php http module
; priority=40
extension=http.so

启用 PHP 模块 'http'

php5enmod http

为开发初始化 composer

composer install

为生产初始化 composer

composer install --no-dev --optimize-autoloader

使用 SmartyStreetsAPI

框架支持

Laravel

SmartyStreetsAPI 为 Laravel 提供服务提供者和外观

在 config/app.php 中的提供者数组中注册服务提供者

'providers' => [
	// ...

	WSIServices\SmartyStreetsAPI\Support\Laravel\Facade::class,
]

在 config/app.php 中的别名数组内添加别名

'aliases' => [
	// ...

	'SmartyStreetsAPI'	=> WSIServices\SmartyStreetsAPI\Support\Laravel\ServiceProvider::class,
]

发布配置文件

php artisan vendor:publish

编辑配置，位于 config/smartystreetsapi.php

return [

	'authentication' => [
		'secret' => [
			'auth-id'		=> '',
			'auth-token'	=> ''
		],
		'website' => [
			'auth-id'		=> ''
		]
	],

	...

	'request-class' => SmartyStreetsAPI\Request\cURL::class,

	...
];

提供SmartyStreets的认证值，并设置您选择的请求类。

命名空间

use WSIServices\SmartyStreetsAPI;

类: Configuration

$configuration = new Configuration($configArray);

类: Factory

$factory = new Factory(new Log);

$factory->setConfiguration($configuration);

类: Service

$service = $factory->getService('us-street-address');

$service->getRequest($optionsArray);

以下服务类型提供了相应的类：

us-street-address: WSIServices\SmartyStreetsAPI\Service\UsStreetAddress
us-zip-code: WSIServices\SmartyStreetsAPI\Service\UsZipCode
us-autocomplete: WSIServices\SmartyStreetsAPI\Service\UsAutocomplete
us-extract: WSIServices\SmartyStreetsAPI\Service\UsExtract
international-addresses: WSIServices\SmartyStreetsAPI\Service\InternationalAddresses
download: WSIServices\SmartyStreetsAPI\Service\Download

**注意：目前只有*us-street-address*已完成。**

美国街道地址服务

此服务有两种修改请求的方法

$service->XStandardizeOnly();

$service->XIncludeInvalid();

下载服务

此服务具有多个资产路径，应在选项数组中设置

us-street-api: /us-street-api/linux-amd64/latest.tar.gz
us-street-data: /us-street-api/data/latest.tar.gz
us-zipcode-api: /us-zipcode-api/linux-amd64/latest.tar.gz
us-zipcode-data: /us-zipcode-api/data/latest.tar.gz
us-autocomplete-api: /us-autocomplete-api/linux-amd64/latest.tar.gz
us-autocomplete-data: /us-autocomplete-api/data/latest.tar.gz

类: Request

有四个请求类型类可供选择。两种是PHP的本地类型（即：file_get_contents和curl），它们没有额外的依赖项。其他两种类型（即：pecl_http2和GuzzleHttp）需要安装一个PECL PHP模块或Composer包。

工具

此库包括文档和测试的实用程序。

phpUnit

PHPUnit是一个针对PHP程序员的测试框架。它是单元测试框架的xUnit架构的一个实例。

从项目根目录运行以下命令

$ ./utilities/phpunit.sh

示例输出

PHPUnit 4.8.22-1-g1ae3a68 by Sebastian Bergmann and contributors.

................................................................. 65 / 97 ( 67%)
................................

Time: 44.39 seconds, Memory: 8.50Mb

OK (97 tests, 135 assertions)

Generating code coverage report in Clover XML format ... done

Generating code coverage report in HTML format ... done

phploc

一个用于快速测量PHP项目大小和分析结构的工具。

从项目根目录运行以下命令

$ ./utilities/phploc.sh

示例输出

phploc 3.0.0-1-gdf11fc5 by Sebastian Bergmann.

Directories                                          9
Files                                               35

Size
  Lines of Code (LOC)                             4943
  Comment Lines of Code (CLOC)                    1191 (24.09%)
  Non-Comment Lines of Code (NCLOC)               3752 (75.91%)
  Logical Lines of Code (LLOC)                     791 (16.00%)
    Classes                                        216 (27.31%)
      Average Class Length                           6
        Minimum Class Length                         0
        Maximum Class Length                        23
      Average Method Length                          2
        Minimum Method Length                        0
        Maximum Method Length                       12
    Functions                                      487 (61.57%)
      Average Function Length                       97
    Not in classes or functions                     88 (11.13%)

Cyclomatic Complexity
  Average Complexity per LLOC                     0.07
  Average Complexity per Class                    2.57
    Minimum Class Complexity                      1.00
    Maximum Class Complexity                     24.00
  Average Complexity per Method                   1.93
    Minimum Method Complexity                     1.00
    Maximum Method Complexity                    21.00

Dependencies
  Global Accesses                                    0
    Global Constants                                 0 (0.00%)
    Global Variables                                 0 (0.00%)
    Super-Global Variables                           0 (0.00%)
  Attribute Accesses                               400
    Non-Static                                     400 (100.00%)
    Static                                           0 (0.00%)
  Method Calls                                     719
    Non-Static                                     694 (96.52%)
    Static                                          25 (3.48%)

Structure
  Namespaces                                        10
  Interfaces                                         2
  Traits                                             0
  Classes                                           20
    Abstract Classes                                 2 (10.00%)
    Concrete Classes                                18 (90.00%)
  Methods                                           83
    Scope
      Non-Static Methods                            82 (98.80%)
      Static Methods                                 1 (1.20%)
    Visibility
      Public Methods                                81 (97.59%)
      Non-Public Methods                             2 (2.41%)
  Functions                                          5
    Named Functions                                  2 (40.00%)
    Anonymous Functions                              3 (60.00%)
  Constants                                          3
    Global Constants                                 0 (0.00%)
    Class Constants                                  3 (100.00%)

Tests
  Classes                                           13
  Methods                                           96

phpDocumentor

一个可以直接从PHP源代码生成文档的工具。

从项目根目录运行以下命令

$ ./utilities/phpdoc.sh

示例输出

此库的文档生成在documentation/api目录。

代码覆盖率

运行phpUnit会在tests/logs目录中生成日志。下面可以看到生成的输出文件及其描述。

coverage.txt: PHPUnit生成的代码覆盖率信息日志的TEXT格式，大致基于Clover使用的格式。
coverage.xml: PHPUnit生成的代码覆盖率信息日志的XML格式，大致基于Clover使用的格式。
report (目录): 代码覆盖率信息的HTML格式；提供包概述、命名空间和类描述、图表和报告（包括错误、标记和已弃元素）。
testdox.txt: PHPUnit TestDox的TEXT格式，用于根据测试生成敏捷项目文档。
testdox.html: PHPUnit TestDox的HTML格式，用于根据测试生成敏捷项目文档。
logfile.tap: Test Anything Protocol (TAP)是Perl测试模块之间的简单文本接口。
logfile.json: JavaScript Object Notation (JSON)是一种轻量级的数据交换格式。

有关phpUnit日志的更多信息，请参阅他们的文档第14章。日志记录和第15章。测试的其他用途。

SmartyStreets 笔记

https://smartystreets.com/docs

状态代码和结果

响应将包含一个带有数值的状态头。
在编写解析响应的代码时，您应该检查此值。
唯一应该读取和解析的响应体是200响应。

美国街道地址 API

https://api.smartystreets.com/street-address?auth-id=123&auth-token=abc

方案: https; 必需；不支持非安全http请求。
主机名: api.smartystreets.com
路径: /street-address
查询字符串: ?auth-id=123&auth-token=abc; 认证信息、输入等。下一节将介绍额外的查询字符串参数。
方法: GET, POST

代码/响应和说明

200 - OK：

成功！ 一个包含零个或多个与请求提供的输入匹配的地址的JSON数组。如果没有提交的地址验证通过，数组将为空([])。GET和POST请求的响应结构相同。
400 - 错误请求：

(无效负载) GET请求缺少街道字段或POST请求的请求体包含无效的JSON。
401 - 未授权：

提供的凭证不正确或与任何现有、有效的凭证不匹配。
402 - 需要付费：

与请求中提交的凭证关联的账户没有有效的订阅。

美国 ZIP 代码 API

https://api.smartystreets.com/zipcode?auth-id=123&auth-token=abc

方案

https

必需；不支持非安全http请求。

主机名

api.smartystreets.com

路径

/zipcode

查询字符串

?auth-id=123&auth-token=abc

认证信息、输入等。下一节将介绍额外的查询字符串参数。

方法

GET, POST

代码/响应和说明

200 - OK：

成功！ 响应体将是一个包含零个或多个与请求提供的输入匹配的JSON数组。GET和POST请求的响应结构相同。
400 - 错误请求：

(无效负载) POST请求的请求体没有查询或包含无效的JSON。
401 - 未授权：

提供的凭证不正确或与任何现有、有效的凭证不匹配。
402 - 需要付费：

与请求中提交的凭证关联的账户没有有效的订阅。

美国自动完成 API

https://autocomplete-api.smartystreets.com/suggest?auth-id=123&auth-token=abc

方案

https

必需；不支持非安全http请求。

主机名

autocomplete-api.smartystreets.com

路径

/suggest

查询字符串

?auth-id=123&auth-token=abc

认证信息、输入等。下一节将介绍额外的查询字符串参数。

方法

GET

代码/响应和说明

200 - OK：

成功！ 响应体是一个JSON对象，包含一个建议数组，基于提供的输入参数进行建议。
400 - 错误请求：

(无效负载) 请求以某种方式格式不正确，无法解析。
401 - 未授权：

提供的凭证不正确或与任何现有、有效的凭证不匹配。
402 - 需要付费：

与请求中提交的凭证关联的账户没有有效的订阅。

美国提取 API

https://extract-beta.api.smartystreets.com/?auth-id=123&auth-token=abc

方案

https

(必需；不支持非安全http请求。

主机名

extract-beta.api.smartystreets.com

路径

/

查询字符串

?auth-id=123&auth-token=abc

认证信息、输入等。下一节将介绍额外的查询字符串参数。

方法

POST

代码/响应和说明

200 - OK：

成功！ 响应体是一个包含关于结果元数据以及零个或多个从请求提供的输入中提取的地址的JSON对象。请参阅下面的注释示例以获取详细信息。
400 - 错误请求：

(无效负载) 请求体为空或格式不正确。
401 - 未授权：

提供的凭证不正确或与任何现有、有效的凭证不匹配。
402 - 需要付费：

与请求中提交的凭证关联的账户没有有效的订阅。
413 - 请求实体过大：

请求体大于64千字节。

验证国际地址

https://international-street.api.smartystreets.com/verify?auth-id=123&auth-token=abc

方案

https

必需；不支持非安全http请求。

主机名

international-street.api.smartystreets.com

路径

/verify

查询字符串

?auth-id=123&auth-token=abc

(需要额外的查询字符串参数；请参阅下一节。

方法

GET

代码/响应和说明

200 - OK：

成功！ 包含零个或多个与请求提供的输入匹配的地址的JSON数组。如果没有提交的地址验证通过，数组将为空([])。
400 - 错误请求：

(无效负载) 请求的输入无法解释。
401 - 未授权：

提供的凭证不正确或与任何现有、有效的凭证不匹配。
402 - 需要付费：

与请求中提交的凭证关联的账户没有有效的订阅。
403 - 禁止：

由于国际服务目前处于限量发布阶段，只有经过批准的账户才能访问该服务。请联系我们以获取账户访问权限。
422 - 不可处理的实体：

GET请求缺少必需的字段。
429 - 请求过多：

在过短的时间内提交了太多具有完全相同输入值的请求。此状态代码传达了由于此类条件（如不断将同一记录发送到API的无限循环）而可能产生的运行过度费用，输入未被处理。欢迎您。
504 - 网关超时：

我们自己的上游数据提供商没有及时响应，请求失败。确实是一个严重但罕见的情况。

下载 API

https://download.api.smartystreets.com/path/to/package?auth-id=123&auth-token=abc

方案

https

必需；不支持非安全http请求。

主机名

download.api.smartystreets.com

路径

/{$pack-path}

请参阅包装列表以获取确切值。

查询字符串

?auth-id=123&auth-token=abc

认证信息、输入等。下一节将介绍额外的查询字符串参数。

方法

GET

代码/响应和说明

307 - 临时重定向：

成功！ 位置响应头将包含实际的下载URL。此链接仅持续几秒钟，因此您需要立即跟随重定向。将-L标志传递给curl命令（如本页上的示例所示）将自动完成此操作。
401 - 未授权：

提供的凭证不正确或与任何现有、有效的凭证不匹配。
402 - 需要付费：

与请求中提交的凭据关联的账户没有活跃的企业订阅。
404 - 未找到：

您请求的软件包不存在，请参阅软件包列表以获取确切的URL路径值。
405 - 方法不允许：

使用的请求方法不允许。请参阅允许的请求方法。

软件包列表

每个软件包都将包含一个包含安装说明和文档的文本文件。

软件包 - 令牌 / URL路径（插入到请求URL中）

美国街道地址 API

us-street-api

us-street-api/linux-amd64/latest.tar.gz

美国街道地址数据

us-street-data

us-street-api/data/latest.tar.gz

美国 ZIP 代码 API

us-zipcode-api

us-zipcode-api/linux-amd64/latest.tar.gz

美国ZIP代码数据

us-zipcode-data

us-zipcode-api/data/latest.tar.gz

美国自动完成 API

us-autocomplete-api

us-autocomplete-api/linux-amd64/latest.tar.gz

美国自动补全数据

us-autocomplete-data

us-autocomplete-api/data/latest.tar.gz

wsiservices / smartystreetsapi

维护者

详细信息

README

目录

WSI-Services SmartyStreetsAPI

关于 SmartyStreets

安装 SmartyStreetsAPI

GIT

Composer

依赖

安装系统依赖项

安装 PECL 依赖项 'raphf'

创建 PECL 'raphf' 配置文件：/etc/php5/mods-available/raphf.ini

启用 PHP 模块 'raphf'

安装 PECL 依赖项 'propro'

创建 PECL 'propro' 配置文件：/etc/php5/mods-available/propro.ini

启用 PHP 模块 'propro'

要定位已安装的库路径，将 {LIBRARY} 替换为 libz，

安装 PECL 依赖项 'pecl_http'

使用找到的库路径回答以下问题

创建 PECL 'http' 配置文件：/etc/php5/mods-available/http.ini

启用 PHP 模块 'http'

为开发初始化 composer

为生产初始化 composer

使用 SmartyStreetsAPI

框架支持

Laravel

命名空间

类: Configuration

类: Factory

类: Service

美国街道地址服务

下载服务

类: Request

工具

phpUnit

phploc

phpDocumentor

代码覆盖率

SmartyStreets 笔记

美国街道地址 API

美国 ZIP 代码 API

美国自动完成 API

美国提取 API

验证国际地址

下载 API

软件包列表