How to Use Places

Contents

The sections below detail the most common uses of the Places API. Please view our API documentation for a full list of the functions available.

Requesting a Location’s Details

  1. Search for a Place using our Reverse Geocoding or Single Search geocoding APIs. You can search by name, address, lat/long coordinates, and more, but your search must include the parameter includeTrimblePlaceIds=true. If a match is found, the geocoding API will return basic details about the Place, including a trimblePlaceId field. This is a unique identifier for the Place that is assigned by Trimble MAPS.

  2. Make a GET call to the /details API using the trimblePlaceId you have just retrieved as the placeId. This will return full details about the Place.

If you want to add your own customPlaceId to the location, follow Steps 1-2 above, and then:

  • Make a POST call to the /customplaceid API, using the trimblePlaceId you have just retrieved. In the POST request body, you can assign your own string to customPlaceId.

  • All future calls for that location’s information can then use either that customPlaceId or the trimblePlaceId as the placeId.

Public Data and Custom Edits

Each Place includes a collection of public data that is available to all users. If you make custom edits to a Place’s contact information or operating hours, or if you add driver notes, that data is private to your account. Public and private data are handled this way in API calls:

  • For GET Place details requests, private edits are returned if they exist. Otherwise, public Trimble MAPS data is returned.
  • GET Place details requests also include a query parameter that allows you to choose whether to return only public data (attributeSource=Trimble) or only private data (attributeSource=Custom) for attributes that can be edited.
  • GET requests to each data attribute’s endpoint for a Place—/contactInfo, /operatinghours, or /notes—will return the public and custom attributes side by side.

Updating Locally Stored Location Information

If your system stores location information locally instead of calling the Places API each time you need a location’s details, the /updatedplaces endpoint can be used to help make sure your data is up to date. It retrieves the trimblePlaceIds for Places that have been modified since a given date. You can:

  • Get updates based solely on a lastModifiedDate timestamp by making a GET request to /updatedplaces. This method returns up to 100 results at once, as well as the lastModifiedTimestamp and lastModifiedRecord of the last record of the response. That last record (timestamp and record ID) can then be used as the input for the next request for 100 results, and so on until you have retrieved all of the IDs of updated Places.

  • Get updates based on a lastModifiedDate timestamp and an array of trimblePlaceIds by making a POST request to /updatedplaces/id. This method accepts 100 trimblePlaceIds per request, so multiple requests may be required to check for updates on all of your Places.

Once you have retrieved the list of trimblePlaceIds for Places that need to be updated, you need to pass each ID in a GET request to /place/{placeId} or /place/{placeId}/details to retrieve the location’s updated information.

Creating a New Place

If you search but cannot find a particular Place in the Trimble MAPS database, the Places API gives you the ability to create a new Place with a POST request to /place. You can include as many details about the Place as you have available.

The new Place will be assigned a unique trimblePlaceId and saved in the Trimble MAPS database. It can then be called and managed like any other Place.

Who Has Access to Your Place?

Only your account will initially have access to the Place you have created. Trimble MAPS may review the Place for inclusion in our public Places database available to all users. If we do, Trimble MAPS will collect only non-personal commercial data regarding the Place. Before it is included, the Place will be:

  • Reviewed and edited for accuracy by our team of mapping experts.
  • Expanded to include all of the details available for other public Places in our database.

Regardless of whether your Place is promoted to the public database, you will still be able to call for its details using the original trimblePlaceId returned when you first created it.

Updating a New Place

Once you have a created a new Place, you can update the Place’s information with a PUT request to /place/{placeId} that includes the new details. You can delete a Place you have created with a DELETE request to /place/{placeId}.

Last updated July 7, 2020.