Places (Search) API Developer's Guide

Entrypoints and Media Types

The entrypoints offer a variety of different models for searching for Points of Interest (POIs) and other locations depending on the desired information flow. An information flow, also known as a user flow, represents an information retrieval pattern in which the response to an initial request to a Search or Discovery entrypoint contains hypermedia links that you can use to request the next/previous set of results, more detailed information about a POI, and other kinds of information. The specific set of hypermedia links available depends on the media types contained in a response to a request.

The image below illustrates some typical information flows.
Figure 1. Sample Information Flows
Note: You are not allowed to download the information locally for all hypermedia links to improve performance or for other reasons.

Search and Discovery Entrypoints

Search and Discovery entrypoints allow users to find places or addresses. The following entrypoints are available:
  • autosuggest: provides a list of suggested search terms, instant results, and refined search links based on the submitted (partial) search term and location context.
  • search: provides specific places based on the submitted text string queries and location context.
  • explore: provides a list of relevant nearby places for a location context.
  • browse: provides a list of places sorted by distance for a location context.
  • here: provides a list of places with addresses that lie within the vicinity of the search location. It is designed to implement features such as "check-in".
  • around: similar to explore, but designed for augmented reality applications.

Media Types, Information Attributes, and Interactivity

Media types refer to data structure types that are both received in responses from and sent in requests to the Places (Search) API. Some media types contain Information Attributes that allow users to obtain more information about places that were returned by a Search or Discovery entrypoint. Examples of information attributes include:
  • base attributes: includes name, location, categories, contacts, a category icon, and so on.
    Note: This media type is always supported.
  • extended attributes: includes information such as opening hours, payment methods, annual closing date/times, disabled access, and so on.
  • images: includes third-party and user-provided images as well their dimensions.
  • reviews: includes user-generated reviews and their source.
  • related places nearby: lists other places that may be of interest to the user.
  • sharing URI: the attribute view in the base attributes offers a link to the best available representation of the place on any operating system, platform, or device.
  • editorial descriptions: the attribute editorials in the media object structure consists of third-party descriptions of a place with their source when available.