Download the PHP package teamzac/points-of-interest without Composer

Search for points of interest

A package, which includes Laravel support, for searching multiple providers of point-of-interest (POI) data. Currently includes support for Google, Yelp, FourSquare, and Here.com.

Installation

You can install the package via composer:

Once installed, Laravel 8+ will auto-discover the package. If you do not, or cannot, use auto-discovery, you may manually install by adding the following to :

If you would like to override the default configuration, you may run:

Usage

This package uses the manager strategy to handle switching between different data providers. You can set a default provider as well as any other providers through the configuration file. If you need to retrieve a specific driver, you can use the driver() method on the POI facade:

This will return the driver instance, on which you can specify your query type. If you omit the explicit call to a driver, you'll receive the default driver specified in the configuration.

Data Providers

We currently support:

• Google Places
• Yelp Fusion
• Here.com Places API
• FourSquare

Query Types

This package supports three types of queries: retrieving a POI based on the unique ID from the provider, matching a POI based on some known attributes, and searching for POIs based on certain criteria.

The match and search query types return a fluent query object on which your search parameters can be set. The retrieve query type only accepts the unique ID;

Retrieve a POI based on the provider's unique ID

If you know the provider's ID for the POI, you can fetch their record using the retrieve query:

Unlike the other two queries, the retrieve query directly returns an instance of .

Matching based on known attributes

If you have some known attributes for a POI and would like to retrieve a matching copy from a specific provider, you should use the match query.

Available methods on the match query are:

The method of the match query returns in instance of .

Searching for POIs

If you want to search around a specific address or lat/lng coordinate pair, you should use the search query.

The method returns an instance of , which is a subclass of that adds a few properties and methods for retrieving additional results. Learn more about the here.

We've done our best to provide a standardized interface across all platforms, even though there are at times significant differences between them. Some providers allow searching within arbitrary geometries and/or bounding boxes, while others only allow you to search near a specified address or lat/lng pair.

Searching near a location

To search near a specific address or location, you can use the method, which accepts an instance of . Address is a value object that holds information about a street address, including the street name/number, city, state, country, postal code, and latitude/longitude pair (which should be an instance of ).

If possible, it's recommended to provide a full address including lat/lng when making your request and let the provider convert it to the correct request format. If your Address does not contain sufficient information to run the query, an will be thrown.

Searching within a geometry or bounding box

Coming soon...

Filtering by category

When available, you may filter your searches by business category. Yelp allows filtering by multiple categories, while Google only allows a single type to be used. If multiple categories are provided to the Google driver, it will use only the first.

We provide a generic set of categories that each provider is responsible for mapping to its own specific category codes. For more information, go here. TODO: add something about this

The following providers support searching within arbitrary polygons:

• Here

The following only allow searching about a specific location:

• Google
• Yelp

Classes

Address

A value object that is used to standardize address syntax across the various platforms.

LatLng

A value object that is used to hold a lat/lng coordinate pair

Place

A value object that is used to standardized POI responses across the various platforms. You most likely will not need to create an instance of this object directly unless you're extending the by adding a new provider.

PlaceCollection

The is a subclass of that provides the ability to query for additional results when available.

Extending

If you need to add additional data providers, you can extend the Manager class.

Your provider should implement the interface, which includes the following methods:

match()

The method accepts an optional search term and returns a query object that implements .

The requires the following methods:

The method should return an instance of .

search()

The method accepts an optional search term and returns a query object that implements .

The requires the following methods:

The method should return an instance of .

retrieve()

The method accepts an ID and returns an instance of .

Testing

Changelog

Please see CHANGELOG for more information what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security

If you discover any security related issues, please email [email protected] instead of using the issue tracker.

Credits

• Chad Janicek
• All Contributors
• Laravel Package Boilerplate

License

The MIT License (MIT). Please see License File for more information.