Place Search Api

Master

Dev

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

• PHP 7.0
• Silex

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

• UML class diagram: class.diagram.png
• Use case diagram: activity.diagram.png
• Component diagram: component.diagram.png

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.