Places

A place resource maps geographical coordinates to a known real-world location (a shop, an office, a park, etc.) where a product or Thng may be interacted within. It can be thought of as defining a fixed location, such as a manufacturing warehouse that every product will be manufactured at, as opposed to an incidental location that a Thng may have. As well as physical coordinates, places can contain conventional street address information, but these are not dynamically linked or validated (coordinates entered bear no relation to the address fields specified).

Places can be used to specify a Thng or action location instead of a set of physical coordinates. See the examples below to learn more.

API Status General Availability: /places /places/:placeId

PlaceDocument Data Model

See also: ScopesDocument, AddressDocument

Filterable Fields

This resource type can be filtered using the following fields and operators.

AddressDocument Data Model

Create a Place

❗Partial updates and position

If you PUT a partial update to an existing /places resource, please note that the position object will be cleared if it is not included in your payload.

Places are created using a POST request to the /places resource containing a JSON document.

Read a place

Perform a GET request on the /places resource including the place's ID to read it.

Read All Places

Read all places associated with an account. The result may be paginated if there are more than 30 items.

Update a Place

Delete a Place

To delete a place, simply send a DELETE to the place URL including the placeId. This action cannot be undone.

Get All Places Near Origin

The following request returns a (paginated) list of all places within a radius of a longitude and latitude location origin, sorted by distance. The query parameters are:

• lon - Double Longitude of the search origin.

• lat - Double Latitude of the search origin.

• maxDist - Integer The radius from the origin in kilometres.

Set a Thng's Location to a Place

It is possible to set a Thng's location to a place by adding a location history item with the place ID.

Set an Action's Location to a Place

Similar to setting a Thng's location to a place, it is also possible to set an action's location to a place by its ID within the location object, and setting locationSource to "place".