Details
-
Change Request
-
Resolution: Unresolved
-
P1: Critical
-
None
-
None
Description
Places API
Summary
The Places API provides ways to discover, retrieve, create and modify the place information.
Definition of a Place
The term Place refers to any place on earth; This definition spans:
Places of (public) interest (POI)
Places of (personal) interest (Favorites)
Addresses of Buildings (Locations)
Named areas and regions
Relationships with the Landmarks API
The Places API will supersede the Landmarks API. A place conceptually may be comprised of a number of locations(coord + address)(each location may be a different building) while a landmark is a special kind of location and is thus a somewhat limited concept.
Core attributes/Information Domain
Core attributes are a set of basic information about a place. Additional aggregated information is assigned to a certain information domain (e.g. "business information", "review", "media", "event", "visited by", "references"...).
Variation between place providers
The API will be flexible enough to facilitate variations of along following dimensions
Visibility:- whether a provider supports the notion of public/private places
Connectivity:- whether a provider retrieves places from and online or offline data source
Supported/Unsupported actions:- eg some providers may allow check-in functionality while other providers do not.
Use Case
| The user | may discover/search for places |
|
| The user | may save a place |
|
| The user | may remove place | |
| The user | may edit a place |
|
| The user | may interact with a place(if supported) |
|
| The user | may create a tag | |
| The user | may tag a place |
|
| The user | may delete a tag | |
| The user | may retrieve a list/tree of categories | |
| The user | may assign a categor(y/ies) to a place. | |
| The user | can import place information |
|
| The user | can export place information |
|
| The user | can share a place by sending a place link via email sms | |
| The user | can synchronize a data source that supports online and offline modes | |
| The user | can authenticate themselves to a particular service provider | |
| The backend | may track usage statistics | (still TBD) |
| The developer | can create their own data source for places. | |
| The developer | can choose which data source their data will come from. | |
| The developer | can at runtime detect the capabilities of a particular data source. |
Tags vs categories
The major difference between tags and categories are that categories are groupings predefined by the service provider whilst tags are created by the user. Each user thus has their own personalized set of tags.
Another difference is categories may have a hierarchical tree structure while tags are flat.
Non functional requirements:
- All operations will take place asynchronously.
Scope
- Aggregating place data from multiple sources is not a considered use case.
- Notifications for added/remove places is not supported (this is currently available in the landmarks API).
- Searching by specific attributes such as street, city etc is not supported (this is currently available in the landmarks API).
- Place visibility beyond public and private will not be supported. The API will not handle a case where some places are visible by users who belong to a certain group.
Attribution
Some places may have sources that depending on terms and conditions may require attribution by showing a banner or link.
Access to the API
It may require to authenticate the applications that want to use the Places API depending on the terms and conditions of the underlying services that implements the service interfaces. E.g. user's authentication is required to use "write features" (create a place, add image, add review etc.).