How to Use Places
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
Search for a Place using our Single Search geocoding API. 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
trimblePlaceIdfield. This is a unique identifier for the Place that is assigned by Trimble Maps.
Make a GET call to the /details API using the
trimblePlaceIdyou 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
trimblePlaceIdyou have just retrieved. In the POST request body, you can assign your own string to
All future calls for that location’s information can then use either that
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
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
lastModifiedDatetimestamp by making a GET request to /updatedplaces. This method returns up to 100 results at once, as well as the
lastModifiedRecordof 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
lastModifiedDatetimestamp and an array of
trimblePlaceIdsby making a POST request to /updatedplaces/id . This method accepts 100
trimblePlaceIdsper 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
to retrieve the location’s updated information.