RESTful APIs

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 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 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.

Bulk Requests for Places

The /contains/bulk endpoint returns all of the places that contain a given list of latitude/longitude coordinates. Each POST request can include an array of up to 50 pairs of coordinates. Your request can also include a buffer parameter, which is the distance in meters from each pair of coordinates that you would also like to search for places.

Sample Request 

curl --location 'https://api.trimblemaps.com/places/v1/contains/bulk' \
--header 'Authorization: Bearer {Token}' \
--header 'Content-Type: application/json' \
--data '[
    {
        "lat": 33.744607149,
        "lon": -84.592730631
    },
    {
        "lat": 41.275963432,
        "lon": -75.498662168
    }
]'

Sample Response 

[
  {
    "cooordinates": {
      "lat": 33.744607149,
      "lon": -84.592730631
    },
    "result": {
      "count": 2,
      "data": [
        {
          "trimblePlaceId": "0xlDNnkftfu0qWsE26dmSkjA",
          "name": "Amazon #ATL8",
          "siteName": "Amazon #ATL8",
          "customPlaceId": null,
          "placeClassification": "Premium",
          "address": {
            "streetAddress": "2201 Thornton Road",
            "extendedAddress": null,
            "streetNumber": null,
            "city": "Lithia Springs",
            "county": null,
            "state": {
              "name": "Georgia",
              "abbrv": "GA"
            },
            "country": {
              "name": "United States",
              "abbrv": "US"
            },
            "postalCode": "30122"
          },
          "geometry": {
            "type": "Point",
            "coordinates": [
              -84.592730631,
              33.744607149
            ]
          }
        },
        {
          "trimblePlaceId": "0xPykuFJHGRFWJMlNPFxACrQ",
          "name": "Amazon Fulfillment Ctr",
          "siteName": "Amazon #ATL8",
          "customPlaceId": null,
          "placeClassification": "Premium",
          "address": {
            "streetAddress": "2201 Thornton Rd",
            "extendedAddress": null,
            "streetNumber": null,
            "city": "Lithia Springs",
            "county": null,
            "state": {
              "name": "Georgia",
              "abbrv": "GA"
            },
            "country": {
              "name": "United States",
              "abbrv": "US"
            },
            "postalCode": "30122"
          },
          "geometry": {
            "type": "Point",
            "coordinates": [
              -84.593475,
              33.744542
            ]
          }
        }
      ]
    }
  },
  {
    "cooordinates": {
      "lat": 41.275963432,
      "lon": -75.498662168
    },
    "result": {
      "count": 2,
      "data": [
        {
          "trimblePlaceId": "0x3Pql0X3E2kOLbd37_MWX-Q",
          "name": "Amazon #AVP3",
          "siteName": "Amazon #AVP3",
          "customPlaceId": null,
          "placeClassification": "Premium",
          "address": {
            "streetAddress": "298 1st Avenue",
            "extendedAddress": null,
            "streetNumber": null,
            "city": "Gouldsboro",
            "county": null,
            "state": {
              "name": "Pennsylvania",
              "abbrv": "PA"
            },
            "country": {
              "name": "United States",
              "abbrv": "US"
            },
            "postalCode": "18424"
          },
          "geometry": {
            "type": "Point",
            "coordinates": [
              -75.498662168,
              41.275963432
            ]
          }
        },
        {
          "trimblePlaceId": "0x_TsGk8BjAF2My4BHYxN4eg",
          "name": "Amazon Fulfillment Ctr",
          "siteName": "Amazon #AVP3",
          "customPlaceId": null,
          "placeClassification": "Premium",
          "address": {
            "streetAddress": "298 1st Ave",
            "extendedAddress": null,
            "streetNumber": null,
            "city": "Gouldsboro",
            "county": null,
            "state": {
              "name": "Pennsylvania",
              "abbrv": "PA"
            },
            "country": {
              "name": "United States",
              "abbrv": "US"
            },
            "postalCode": "18424"
          },
          "geometry": {
            "type": "Point",
            "coordinates": [
              -75.499076,
              41.275745
            ]
          }
        }
      ]
    }
  }
]
Last updated May 10, 2024.
API Endpoint:
AWS Azure
Contents