README

一个用于搜索多个POI数据提供者的包，包括Laravel支持。目前包括对Google、Yelp、FourSquare和Here.com的支持。

安装

您可以通过composer安装此包

composer require teamzac/points-of-interest

安装后，Laravel 8+将自动发现该包。如果您不使用自动发现，或无法使用自动发现，您可以通过向config/app.php中添加以下内容来手动安装

    // providers
    \TeamZac\POI\PointsOfInterestServiceProvider::class,
    
    // aliases
    'POI' => \TeamZac\POI\Facades\POI::class,

如果您想覆盖默认配置，您可以运行

php artisan vendor:publish --provider="TeamZac\POI\PointsOfInterestServiceProvider"

使用方法

此包使用管理策略来处理在不同数据提供者之间切换。您可以通过配置文件设置默认提供者以及任何其他提供者。如果您需要检索特定的驱动程序，您可以使用POI外观上的driver()方法

POI::driver('google');

这将返回驱动程序实例，您可以在其中指定查询类型。如果您省略了对驱动程序的显式调用，您将收到配置中指定的默认驱动程序。

数据提供者

我们目前支持

Google Places
Yelp Fusion
Here.com Places API
FourSquare

查询类型

此包支持三种类型的查询：根据提供者的唯一ID检索POI，基于某些已知属性匹配POI，以及基于某些标准搜索POI。

匹配和搜索查询类型返回一个流畅的查询对象，您可以在其中设置搜索参数。检索查询类型仅接受唯一ID；

基于提供者的唯一ID检索POI

如果您知道POI的提供者ID，您可以使用检索查询获取他们的记录

$place = POI::retrieve('provider-id');

$place = POI::driver('yelp')->retrieve('provider-id');

与另两个查询不同，检索查询直接返回一个TeamZac\POI\Support\Place的实例。

基于已知属性匹配

如果您有一些关于POI的已知属性，并且想从特定提供者中检索匹配的副本，您应该使用匹配查询。

$query = POI::match('walmart supercenter')
    ->near(Address::make([
        'street' => '123 Main Street',
        'city' => 'Fort Worth',
        'state' => 'Texas',
        'country' => 'US',
        'postalCode' => 76102,
        'latLng' => LatLng::make(32, -97)
    ]);
    
$place = $query->get();

匹配查询上可用的方法是

$query->search('search term')
    ->address(/** @var TeamZac\POI\Support\Address */)
    ->phone(/** use a phone number instead of a search query, where available */);
    
// use the get() method to perform the query

匹配查询的get()方法返回一个TeamZac\POI\Support\Place的实例。

搜索POI

如果您想搜索特定地址或经纬度坐标对周围的内容，您应该使用搜索查询。

$query = POI::search(/** optional search term goes here */);

$collection = $query->get();

get()方法返回一个TeamZac\POI\Support\PlaceCollection的实例，它是Illuminate\Support\Collection的子类，添加了一些属性和方法以检索更多结果。有关更多信息，请参阅此处。

尽管在某些时候平台之间存在显著差异，但我们已尽力为所有平台提供标准化接口。一些提供者允许在任意几何形状和/或边界框内进行搜索，而其他提供者只允许您在指定的地址或经纬度对附近进行搜索。

在位置附近搜索

要搜索特定地址或位置附近的内容，您可以使用near()方法，该方法接受一个TeamZac\POI\Support\Address的实例。地址是一个值对象，包含有关街道地址的信息，包括街道名称/编号、城市、州、国家、邮政编码和经纬度对（这应该是一个TeamZac\POI\Support\LatLng的实例）。

// Google requires a lat/lng pair with optional radius
POI::driver('google')->search()->near(Address::make([
    'latLng' => LatLng::make(32, -97),
])->radius(500); // meters

// Yelp requires an address, including country code
POI::driver('yelp')->search()->near(Address::make([
    'street' => '123 Main Street',
    'city' => 'Fort Worth',
    'state' => 'Texas',
    'postalCode' => 76102,
    'country' => 'US',
]);

如果可能的话，建议在提交请求时提供完整的地址（包括经纬度），并让服务提供者将其转换为正确的请求格式。如果您的地址信息不足以运行查询，将抛出InsufficientAddressExeption异常。

在几何形状或边界框内搜索

即将推出...

按类别过滤

当可用时，您可以根据商业类别过滤搜索结果。Yelp允许按多个类别过滤，而Google只允许使用单个类型。如果向Google驱动程序提供了多个类别，它将只使用第一个。

$query = POI::search()->near(/** @var Address */);

// you can narrow your search by category where available
// if the provider does not support this option, it will result in a no-op
$query->categories(['retail', 'restaurant']);

我们提供了一套通用的类别，每个提供者负责将其映射到自己的特定类别代码。更多信息请访问[此处]。待办：添加有关此信息的内容

以下提供者支持在任意多边形内搜索

这里

以下只允许在特定位置进行搜索

Google
Yelp

类别

地址

一个值对象，用于在各种平台间标准化地址语法。

Address::make([
    'street' => '123 Main Street',
    // etc
]);

经纬度

一个值对象，用于存储经纬度坐标对。

LatLng::make(32, -97);

地点

一个值对象，用于在各种平台间标准化POI响应。除非您通过添加新提供者扩展TeamZac\POI\Manager，否则通常不需要直接创建此对象的实例。

$place = POI::driver('google')->retrieve('provider-id');

$place->getProvider();      // 'google'
$place->getId();            // 'provider-id'
$place->getName();          // business name
$place->getAddress();       // TeamZac\POI\Support\Address
$place->getPhone();         // phone number
$place->getCategories();    // array of category strings
$place->getRaw();           // array containing the raw results from the provider

地点集合

TeamZac\POI\Support\PlaceCollection是Illuminate\Support\Collection的子类，它提供了在结果可用时查询额外结果的能力。

$collection = POI::search()->near($address)->get();

// get a new instance of PlaceCollection containing the next page of search results
$collection->nextPage();

// get the total number of results found
$collection->getTotal();

扩展

如果您需要添加额外的数据提供者，可以扩展Manager类。

POI::extend('new-provider', function($app) {
    // create and return your driver here
});

您的提供者应实现TeamZac\POI\Contracts\ProviderInterface接口，该接口包含以下方法

match()

match()方法接受一个可选的搜索词，并返回一个实现TeamZac\POI\Contracts\MatchQueryInterface的查询对象。

MatchQueryInterface需要以下方法

search($term = null)
phone($number = null)
near(Address $addess)
get()

get()方法应返回一个TeamZac\POI\Support\Place的实例。

search()

search()方法接受一个可选的搜索词，并返回一个实现TeamZac\POI\Contracts\SearchQueryInterface的查询对象。

SearchQueryInterface需要以下方法

search($term = null)
near(Address $address)
within($tbd)
get()

get()方法应返回一个TeamZac\POI\Support\PlaceCollection的实例。

retrieve()

retrieve()方法接受一个ID，并返回一个TeamZac\POI\Support\Place的实例。

测试

composer test

变更日志

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

贡献

请参阅贡献指南获取详细信息。

安全

如果您发现任何安全相关的问题，请通过电子邮件chad@zactax.com联系，而不是使用问题跟踪器。

致谢

许可证

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

teamzac / points-of-interest

维护者

详细信息