PHP Classes
elePHPant
Icontem

PHP Location Based Search API: API server for searching places near a location

Recommend this page to a friend!
  Info   View files Example   View files View files (125)   DownloadInstall with Composer Download .zip   Reputation   Support forum   Blog    
Last Updated Ratings Unique User Downloads Download Rankings
2017-01-09 (8 months ago) RSS 2.0 feedNot enough user ratingsTotal: 107 All time: 8,708 This week: 656Up
Version License PHP version Categories
placesearchapi 1.0.0MIT/X Consortium ...7Searching, Web services, Geography, P...
Description Author

This package implements an API server for searching places near a location.

It provides controller classes that handle requests for API end points to perform queries for locations near given coordinates.

The package uses Google Maps API for searching locations but it can user other APIs from different providers.

Innovation Award
PHP Programming Innovation award nominee
January 2017
Number 8


Prize: 1 year subscription to the Basic Plan of an API product of choice
Many geo-location based applications provide means to search for locations near a given region.

This package implements a REST API for performing searches for places near a given location using the Google Maps API as information provided.

Manuel Lemos
  Performance   Level  
Name: Sergii Pryz <contact>
Classes: 9 packages by
Country: Ukraine Ukraine
Age: 33
All time rank: 161128 in Ukraine Ukraine
Week rank: 503 Up4 in Ukraine Ukraine Up
Innovation award
Innovation award
Nominee: 4x

Details

Place Search Api

SensioLabsInsight

Master

Build Status Coverage Status

Dev

Build Status Coverage Status

RESTfull API to provide search places around choosing radius. In other words it can answer to "Where are bars in 2km near me?".

PlaceSearchApi is using Google Places API as a search source. But it's possible to integrate different search engine using applications Adapter API.

Requirements

Installation

  • Run composer install --no-dev
  • Create /config/parameters.yaml and put data using parameters.yaml.dist as example

Specification

Endpoint

The endpoint is http://place-search.dev/api/v1 where * place-search.dev - development domain * api - indicate that it's api * v1 - version parameter

Resources

Name | Method | Required parameters | Optional parameters | Example --- | --- | --- | --- | --- bar | GET | location, radius | language | GET:bar?location="54.3476107,18.6503288"&radius="2000"

Parameters

Name | Type | Default | Description | Value range --- | --- | --- | --- | --- location | String,String | 54.3476107,18.6503288 | Comma separated latitude, longitude. Default value is Neptune?s Fountain in Gda?sk| For latitude number in range [-90, 90]. For longitude number in range [-180, 180]. radius | Integer | 2000 | Radius over location point in meters | Radius should be in range [1, 50 000] language | String | en | Two character language code | See the list of supported languages by Google Places.

Response

Bar

Here is request-response example for Bar resource Request:

GET:bar?location="54.3476107,18.6503288"&radius="2000"

Response:

{
    "data": [
        {
            "id" : "21a0b251c9b8392186142c798263e289fe45b4aa",
            "placeId" : "ChIJyWEHuEmuEmsRm9hTkapTCrk",
            "location" : {
               "lat" : -33.870775,
               "lng" : 151.199025
            },
            "name" : "Rhythmboat Cruises",
            "icon" : "http://maps.gstatic.com/mapfiles/place_api/icons/travel_agent-71.png",
            "vicinity" : "Pyrmont Bay Wharf Darling Dr, Sydney",
            "scope" : "GOOGLE"
        }
    ],
    "count": 1,
    "code": 200
}

where: * data - bar's collection * data[0] - first bar, the bar structure is a limit version of Google Place Search Response * count - number of entities inside collection * code - http status code

The limit for number of bars in response is 20. That limitation is a result of MVP choose and can be extended in next version. Please view feature candidate document or open an issue to start discussion.

Errors

All errors message have one format that is described bellow:

{
    "msg": "500 Internal server error",
    "code": 500
}

HTTP codes

Table bellow shows list of supported HTTP codes.

Code | Message | Description --- | --- | --- 500 | 500 Internal Server Error | Critical application error 501 | 501 Not Implemented | HTTP method was not implemented for that resource 404 | 404 Not Found | Resource was not found

Architecture

Architecture is based on Hexagonal Architecture. To see what that architecture involve please visit:

  1. Matthias Noback: "Hexagonal architecture - message-oriented software design", PHPCon-2015
  2. Fideloper: Hexagonal Architecture

PlaceSearchApi has those layers:

  1. Framework: Silex
  2. Application: App
  3. Domain: Search, Engine
  4. Core Domain: Model

Extensibility

PlaceSearchApi follows layer architecture with DI using Interfaces therefore it's possible to provide any modification.

How to change Framework

PlaceSearchApi is using Silex with controllers as a services so to use another framework:

  • inject controllers services to new ones
  • put DI instantiating to new frameworks bootstrap

Add new place type

PlaceSearchApi supports for now Bar to add more places it's need only send parameter to Service/Place/GetService.

Extend response data

To make possible return working hours in api response it's need:

  • update Model\Data\Place value objects interface and builders
  • update Engine\GoogleSearchPlace\SchemaCollectionFactory

Use different HTTP client

  • implement interface Search\Api\Http\ClientInterface
  • update DI configuration

Dependency

That section describes how PlaceSearchApi deals with dependency.

Framework dependency

PlaceSearchApi does not have Framework dependency:

  • all controllers are services
  • domain does not use Frameworks components

3-rd party dependency

PlaceSearchApi uses own Interfaces and wrappers over 3-rd party applications additionally it's catch and resend own Exceptions.

Code coupling

Having layer architecture additional with composition bring independent and clear communication between modules.

Here is a list of rules that were placed over PlaceSearchApi:

  • layer SHOULD throw only it's own exceptions
  • message SHOULD go directly from top layer to inner one not vice versa
  • using interfaces as dependency
  • keeping value objects immutable
  • depending on abstraction

Documentation

Developing

To configure developing environment please:

  1. Install and run Docker container
  2. Run inside project root in Docker container composer install

Debug

Docker container is configured to use xDebug.

Proxy

Please use proxy client to see requests to Google Places API, e.g. Fiddler for Windows or Fiddler for Mono for Linux machine.

Future features candidates

Feature candidates are in separate file. It's a list of ideas that were appeared during development process. After review some of them will be moved to issues with feature label.

Contribution

If you find this project worth to use please add a star. Follow changes to see all activities. And if you see room for improvement, proposals please feel free to create an issue or send pull request. Here is a great guide to start contributing.

Please note that this project is released with a Contributor Code of Conduct. By participating in this project and its community you agree to abide by those terms.

License

PlaceSearchApi is licensed under the MIT License. Please see the LICENSE file for details.

  Files folder image Files  
File Role Description
Files folder imageconfig (2 files)
Files folder imagedev (2 directories)
Files folder imagedoc (1 directory)
Files folder imagesrc (1 file, 4 directories)
Files folder imageweb (3 files)
Accessible without login Plain text file .travis.yml Data Auxiliary data
Accessible without login Plain text file CHANGELOG.md Data Auxiliary data
Accessible without login Plain text file composer.json Data Auxiliary data
Accessible without login Plain text file composer.lock Data Auxiliary data
Accessible without login Plain text file FEATURE.CANDIDATE.md Data Auxiliary data
Accessible without login Plain text file LICENSE.txt Lic. License
Accessible without login Plain text file README.md Doc. Documentation

  Files folder image Files  /  config  
File Role Description
  Accessible without login Plain text file parameters.yml.dist Data Auxiliary data
  Accessible without login Plain text file services.yml Data Auxiliary data

  Files folder image Files  /  dev  
File Role Description
Files folder imagedocker (2 files, 1 directory)
Files folder imagetests (1 file, 2 directories)

  Files folder image Files  /  dev  /  docker  
File Role Description
Files folder imageapp (1 file, 1 directory)
  Accessible without login Plain text file docker-compose.yml Data Auxiliary data
  Accessible without login Plain text file README.md Doc. Documentation

  Files folder image Files  /  dev  /  docker  /  app  
File Role Description
Files folder imageconfig (1 directory)
  Accessible without login Plain text file Dockerfile Data Auxiliary data

  Files folder image Files  /  dev  /  docker  /  app  /  config  
File Role Description
Files folder imageapache (1 file)

  Files folder image Files  /  dev  /  docker  /  app  /  config  /  apache  
File Role Description
  Accessible without login Plain text file place-search.dev.conf Data Auxiliary data

  Files folder image Files  /  dev  /  tests  
File Role Description
Files folder imageintegration (1 directory)
Files folder imageunit (1 directory)
  Accessible without login Plain text file phpunit.xml.dist Data Auxiliary data

  Files folder image Files  /  dev  /  tests  /  integration  
File Role Description
Files folder imagesrc (1 file, 2 directories)

  Files folder image Files  /  dev  /  tests  /  integration  /  src  
File Role Description
Files folder imageFixture (2 directories)
Files folder imageResource (3 files)
  Plain text file BaseTest.php Class Class source

  Files folder image Files  /  dev  /  tests  /  integration  /  src  /  Fixture  
File Role Description
Files folder imagedata (1 file)
Files folder imageGuzzle (1 file)

  Files folder image Files  /  dev  /  tests  /  integration  /  src  /  Fixture  /  data  
File Role Description
  Accessible without login Plain text file google.bar.json Data Auxiliary data

  Files folder image Files  /  dev  /  tests  /  integration  /  src  /  Fixture  /  Guzzle  
File Role Description
  Plain text file ClientFactory.php Class Class source

  Files folder image Files  /  dev  /  tests  /  integration  /  src  /  Resource  
File Role Description
  Plain text file BarTest.php Class Class source
  Plain text file ErrorTest.php Class Class source
  Plain text file IndexTest.php Class Class source

  Files folder image Files  /  dev  /  tests  /  unit  
File Role Description
Files folder imagesrc (1 file, 4 directories)

  Files folder image Files  /  dev  /  tests  /  unit  /  src  
File Role Description
Files folder imageApp (2 directories)
Files folder imageEngine (1 directory)
Files folder imageModel (2 files, 1 directory)
Files folder imageSearch (1 file, 2 directories)
  Plain text file BaseTest.php Class Class source

  Files folder image Files  /  dev  /  tests  /  unit  /  src  /  App  
File Role Description
Files folder imageController (2 files)
Files folder imageService (2 directories)

  Files folder image Files  /  dev  /  tests  /  unit  /  src  /  App  /  Controller  
File Role Description
  Plain text file BarControllerTest.php Class Class source
  Plain text file ErrorControllerTest.php Class Class source

  Files folder image Files  /  dev  /  tests  /  unit  /  src  /  App  /  Service  
File Role Description
Files folder imageError (3 files)
Files folder imagePlace (1 file)

  Files folder image Files  /  dev  /  tests  /  unit  /  src  /  App  /  Service  /  Error  
File Role Description
  Plain text file IternalServerServiceTest.php Class Class source
  Plain text file NotFoundServiceTest.php Class Class source
  Plain text file NotImplementedServiceTest.php Class Class source

  Files folder image Files  /  dev  /  tests  /  unit  /  src  /  App  /  Service  /  Place  
File Role Description
  Plain text file GetServiceTest.php Class Class source

  Files folder image Files  /  dev  /  tests  /  unit  /  src  /  Engine  
File Role Description
Files folder imageGoogleSearchPlace (2 files, 1 directory)

  Files folder image Files  /  dev  /  tests  /  unit  /  src  /  Engine  /  GoogleSearchPlace  
File Role Description
Files folder imageHttp (1 file)
  Plain text file PlaceRepositoryTest.php Class Class source
  Plain text file SchemaCollectionFactoryTest.php Class Class source

  Files folder image Files  /  dev  /  tests  /  unit  /  src  /  Engine  /  GoogleSearchPlace  /  Http  
File Role Description
  Plain text file CrawlerTest.php Class Class source

  Files folder image Files  /  dev  /  tests  /  unit  /  src  /  Model  
File Role Description
Files folder imageService (3 files)
  Plain text file MapperTest.php Class Class source
  Plain text file ObjectManagerTest.php Class Class source

  Files folder image Files  /  dev  /  tests  /  unit  /  src  /  Model  /  Service  
File Role Description
  Plain text file LocationBuilderTest.php Class Class source
  Plain text file PlaceBuilderTest.php Class Class source
  Plain text file SchemaBuilderTest.php Class Class source

  Files folder image Files  /  dev  /  tests  /  unit  /  src  /  Search  
File Role Description
Files folder imageHandler (4 files)
Files folder imageService (1 file)
  Plain text file ConfigTest.php Class Class source

  Files folder image Files  /  dev  /  tests  /  unit  /  src  /  Search  /  Handler  
File Role Description
  Plain text file AbstractHandlerTest.php Class Class source
  Plain text file CacheTest.php Class Class source
  Plain text file EmptyDataTest.php Class Class source
  Plain text file EngineTest.php Class Class source

  Files folder image Files  /  dev  /  tests  /  unit  /  src  /  Search  /  Service  
File Role Description
  Plain text file ResponseBuilderTest.php Class Class source

  Files folder image Files  /  doc  
File Role Description
Files folder imageuml (4 files)

  Files folder image Files  /  doc  /  uml  
File Role Description
  Accessible without login Image file activity.diagram.png Data Auxiliary data
  Accessible without login Image file class.diagram.png Data Auxiliary data
  Accessible without login Image file component.diagram.png Icon Icon image
  Accessible without login Plain text file README.md Doc. Documentation

  Files folder image Files  /  src  
File Role Description
Files folder imageApp (5 directories)
Files folder imageEngine (1 directory)
Files folder imageModel (2 files, 4 directories)
Files folder imageSearch (1 file, 6 directories)
  Accessible without login Plain text file app.php Example Example script

  Files folder image Files  /  src  /  App  
File Role Description
Files folder imageApi (1 file)
Files folder imageController (3 files, 1 directory)
Files folder imageDi (1 file, 2 directories)
Files folder imageException (3 files)
Files folder imageService (1 file, 2 directories)

  Files folder image Files  /  src  /  App  /  Api  
File Role Description
  Plain text file ServiceInterface.php Class Class source

  Files folder image Files  /  src  /  App  /  Controller  
File Role Description
Files folder imageProvider (2 files)
  Plain text file BarController.php Class Class source
  Plain text file ErrorController.php Class Class source
  Plain text file IndexController.php Class Class source

  Files folder image Files  /  src  /  App  /  Controller  /  Provider  
File Role Description
  Plain text file BarProvider.php Class Class source
  Plain text file IndexProvider.php Class Class source

  Files folder image Files  /  src  /  App  /  Di  
File Role Description
Files folder imageGoogleSearchPlace (1 file)
Files folder imageGuzzle (1 file)
  Plain text file ConfigFactory.php Class Class source

  Files folder image Files  /  src  /  App  /  Di  /  GoogleSearchPlace  
File Role Description
  Plain text file SchemaCollectionFactory.php Class Class source

  Files folder image Files  /  src  /  App  /  Di  /  Guzzle  
File Role Description
  Plain text file ClientFactory.php Class Class source

  Files folder image Files  /  src  /  App  /  Exception  
File Role Description
  Plain text file ExceptionInterface.php Class Class source
  Plain text file InvalidArgumentException.php Class Class source
  Plain text file RuntimeException.php Class Class source

  Files folder image Files  /  src  /  App  /  Service  
File Role Description
Files folder imageError (3 files)
Files folder imagePlace (1 file)
  Plain text file ServiceProvider.php Class Class source

  Files folder image Files  /  src  /  App  /  Service  /  Error  
File Role Description
  Plain text file InternalServerService.php Class Class source
  Plain text file NotFoundService.php Class Class source
  Plain text file NotImplementedService.php Class Class source

  Files folder image Files  /  src  /  App  /  Service  /  Place  
File Role Description
  Plain text file GetService.php Class Class source

  Files folder image Files  /  src  /  Engine  
File Role Description
Files folder imageGoogleSearchPlace (2 files, 1 directory)

  Files folder image Files  /  src  /  Engine  /  GoogleSearchPlace  
File Role Description
Files folder imageHttp (1 file)
  Plain text file PlaceRepository.php Class Class source
  Plain text file SchemaCollectionFactory.php Class Class source

  Files folder image Files  /  src  /  Engine  /  GoogleSearchPlace  /  Http  
File Role Description
  Plain text file Crawler.php Class Class source

  Files folder image Files  /  src  /  Model  
File Role Description
Files folder imageApi (3 files, 2 directories)
Files folder imageData (5 files)
Files folder imageException (4 files)
Files folder imageService (6 files)
  Plain text file Mapper.php Class Class source
  Plain text file ObjectManager.php Class Class source

  Files folder image Files  /  src  /  Model  /  Api  
File Role Description
Files folder imageData (5 files)
Files folder imageService (7 files)
  Plain text file MapperInterface.php Class Class source
  Plain text file ObjectManagerInterface.php Class Class source
  Plain text file PlaceRepositoryInterface.php Class Class source

  Files folder image Files  /  src  /  Model  /  Api  /  Data  
File Role Description
  Plain text file CollectionInterface.php Class Class source
  Plain text file EmptyDataInterface.php Class Class source
  Plain text file LocationInterface.php Class Class source
  Plain text file PlaceInterface.php Class Class source
  Plain text file SchemaInterface.php Class Class source

  Files folder image Files  /  src  /  Model  /  Api  /  Service  
File Role Description
  Plain text file CollectionFactoryInterface.php Class Class source
  Plain text file LocationBuilderInterface.php Class Class source
  Plain text file PlaceBuilderInterface.php Class Class source
  Plain text file PlaceCollectionBuilderInterface.php Class Class source
  Plain text file SchemaBuilderInterface.php Class Class source
  Plain text file SchemaCollectionBuilderInterface.php Class Class source
  Plain text file SchemaCollectionFactoryInterface.php Class Class source

  Files folder image Files  /  src  /  Model  /  Data  
File Role Description
  Plain text file Collection.php Class Class source
  Plain text file EmptyData.php Class Class source
  Plain text file Location.php Class Class source
  Plain text file Place.php Class Class source
  Plain text file Schema.php Class Class source

  Files folder image Files  /  src  /  Model  /  Exception  
File Role Description
  Plain text file ExceptionInterface.php Class Class source
  Plain text file InvalidArgumentException.php Class Class source
  Plain text file RepositoryException.php Class Class source
  Plain text file RuntimeException.php Class Class source

  Files folder image Files  /  src  /  Model  /  Service  
File Role Description
  Plain text file CollectionFactory.php Class Class source
  Plain text file LocationBuilder.php Class Class source
  Plain text file PlaceBuilder.php Class Class source
  Plain text file PlaceCollectionBuilder.php Class Class source
  Plain text file SchemaBuilder.php Class Class source
  Plain text file SchemaCollectionBuilder.php Class Class source

  Files folder image Files  /  src  /  Search  
File Role Description
Files folder imageApi (2 files, 3 directories)
Files folder imageData (2 files)
Files folder imageException (4 files)
Files folder imageHandler (4 files)
Files folder imageHttp (1 file)
Files folder imageService (3 files)
  Plain text file Config.php Class Class source

  Files folder image Files  /  src  /  Search  /  Api  
File Role Description
Files folder imageData (2 files)
Files folder imageHttp (2 files)
Files folder imageService (3 files)
  Plain text file ConfigInterface.php Class Class source
  Plain text file HandlerInterface.php Class Class source

  Files folder image Files  /  src  /  Search  /  Api  /  Data  
File Role Description
  Plain text file ErrorInterface.php Class Class source
  Plain text file ResponseInterface.php Class Class source

  Files folder image Files  /  src  /  Search  /  Api  /  Http  
File Role Description
  Plain text file ClientInterface.php Class Class source
  Plain text file CrawlerInterface.php Class Class source

  Files folder image Files  /  src  /  Search  /  Api  /  Service  
File Role Description
  Plain text file ErrorBuilderInterface.php Class Class source
  Plain text file ErrorCollectionBuilderInterface.php Class Class source
  Plain text file ResponseBuilderInterface.php Class Class source

  Files folder image Files  /  src  /  Search  /  Data  
File Role Description
  Plain text file Error.php Class Class source
  Plain text file Response.php Class Class source

  Files folder image Files  /  src  /  Search  /  Exception  
File Role Description
  Plain text file CrawlerException.php Class Class source
  Plain text file ExceptionInterface.php Class Class source
  Plain text file InvalidArgumentException.php Class Class source
  Plain text file RuntimeException.php Class Class source

  Files folder image Files  /  src  /  Search  /  Handler  
File Role Description
  Plain text file AbstractHandler.php Class Class source
  Plain text file Cache.php Class Class source
  Plain text file EmptyData.php Class Class source
  Plain text file Engine.php Class Class source

  Files folder image Files  /  src  /  Search  /  Http  
File Role Description
  Plain text file Client.php Class Class source

  Files folder image Files  /  src  /  Search  /  Service  
File Role Description
  Plain text file ErrorBuilder.php Class Class source
  Plain text file ErrorCollectionBuilder.php Class Class source
  Plain text file ResponseBuilder.php Class Class source

  Files folder image Files  /  web  
File Role Description
  Accessible without login Image file favicon.ico Data Auxiliary data
  Accessible without login Plain text file index.php Example Example script
  Accessible without login Plain text file robots.txt Data Robots

 Version Control Unique User Downloads Download Rankings  
 100%
Total:107
This week:0
All time:8,708
This week:656Up