Introduction

A Place is a collection of data about a location—ranging from mapping location information, such as its name, address and GPS coordinates, to details about its amenities, truck entrances and exits, parking, hours of operation, and more.

Trimble MAPS maintains an ever-growing Places database that includes tens of thousands of commercial locations across North America that serve the transportation industry. These Places range from distribution centers and manufacturing facilities to truck stops and Wal-Mart overnight parking locations.

The Places API allows you to search for a Place and then request all of its associated location data. You can also add your own custom attributes to a Place, including:

  • A customPlaceId to match your existing ID for the location, making it easy to call that location’s information in the future.
  • Notes for the driver about the Place.
  • Operating hours for the Place.
  • Contact information for the Place.

What Can You Do?

The Places API can be used in any application that requires accurate location information to provide exceptional customer service. For PC*MILER route planning and CoPilot navigation, for example, Places can provide details drivers need for accurate final-mile routing to locations with specific rules for commercial vehicles.

Getting Started

To gain access to the Places API, you must be a Premium Web Services subscriber. If you are not a subscriber, please contact your Trimble MAPS representative or our Sales team for more information.

Resource URL

https://api.trimblemaps.com/places/v1

What is a TrimbleplaceId?

Every location in our Places database is identified by a TrimblePlaceId. That ID ensures you receive the exact same information about a Place—address, contact information, etc.—regardless of whether you are calling the information from your transportation management system (TMS) or accounting software.

For APIs that require a generic placeId parameter, you can use one of two values:

  • The TrimblePlaceId. This is a string value assigned by Trimble MAPS that cannot be changed or deleted.

  • A customPlaceId that you have assigned to the Place. This string value is in addition to the TrimblePlaceId. It can be a more “human readable” value, such as your company’s existing shortcode for the location.

Places API Workflow

To request a location’s details via the Places API, you would:

  1. Search for a Place using our Reverse Geocoding or Single Search 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.

What’s in a Place?

A Place may include all of the following information.

FieldDescriptionData Type
trimblePlaceIdThe unique Trimble MAPS identifier for the Place.string
customPlaceIdYour company’s own identifier (shortcode) for the Place.string
nameThe name of the Place.string
categoryNameThe category for the Place in the Places database.string
addressThe street address of the Place.object
formattedAddressThe address as a single text string.string
geometryThe coordinates of the Place.GeoJSON Point Format
siteThe details of the Site that surrounds the perimeter of a Place. A Site is a boundary polygon on the map that defines an area such as a warehouse, a shopping mall or a business park. It includes site-specific details such as gates where commercial vehicles need to enter or exit.object
amenitiesThe amenities available at the Place.object
parkingInformation about parking at the Place.object
operatingHoursThe hours of operation at the Place.object
contactInfoThe Place’s phone number and web site URL.object
lastModifiedThe last modified date & time for the Place.string

Sample JSON for a Place

{
  "trimblePlaceId": "0x6MTu_03diEyV9O5tusIVFg",
  "customPlaceId": "TRIM057",
  "name": "Schneider Dairy",
  "categoryName": "Distribution Center",
  "address": {
    "streetAddress": "Frank Street",
    "extendedAddress": "4th Floor",
    "streetNumber": "726",
    "city": "Pittsburgh",
    "county": "Allegheny",
    "state": {
      "name": "Pennsylvania",
      "abbrv": "PA"
    },
    "country": {
      "name": "United States",
      "abbrv": "US"
    },
    "postalCode": "15227"
  },
  "formattedAddress": "726 Frank Street, Pittsburgh, PA 15227",
  "geometry": {
    "type": "Point",
    "coordinates": [-79.990648270618, 40.368917670069]
  },
  "site": {
    "id": 1505678743,
    "name": "Schneider Dairy",
    "type": "",
    "gates": [
      {
        "id": 1500857459,
        "type": "Two Way",
        "vehAllowed": ["Truck"],
        "gateToSite": {
          "geometry": {
            "type": "Point",
            "coordinates": [-79.991110273389, 40.370069318755]
          }
        },
        "gateToRoad": {
          "geometry": {
            "type": "Point",
            "coordinates": [-79.991109, 40.37007]
          }
        }
      },
      {
        "id": 1500857460,
        "type": "Two Way",
        "vehAllowed": ["Truck"],
        "gateToSite": {
          "geometry": {
            "type": "Point",
            "coordinates": [-79.9917487945325, 40.3699406148846]
          }
        },
        "gateToRoad": {
          "geometry": {
            "type": "Point",
            "coordinates": [-79.991747, 40.369942]
          }
        }
      },
      {
        "id": 1500857461,
        "type": "Two Way",
        "vehAllowed": ["Auto", "Truck"],
        "gateToSite": {
          "geometry": {
            "type": "Point",
            "coordinates": [-79.9908828548996, 40.3684636442553]
          }
        },
        "gateToRoad": {
          "geometry": {
            "type": "Point",
            "coordinates": [-79.990881, 40.368463]
          }
        }
      }
    ],
    "geometry": {
      "type": "MultiPolygon",
      "coordinates": [
        [
          [
            [-79.9919009475589, 40.3699354170329],
            [-79.9903068220583, 40.3702505038153],
            [-79.9898822559702, 40.3692812114255],
            [-79.9900130970916, 40.3686884210383],
            [-79.990507089081, 40.3686483676337],
            [-79.9906165683867, 40.3684427601571],
            [-79.9906699729261, 40.3683786747098],
            [-79.9911639649154, 40.3685095158313],
            [-79.9910197726591, 40.3689260712385],
            [-79.9917647659835, 40.3692037748433],
            [-79.9919009475589, 40.3699354170329]
          ]
        ]
      ]
    },
    "lastModified": "2020-01-14T17:29:20.999Z"
  },
  "operatingHours": {
    "sunday": {
      "hours": [
        {
          "open": "0000",
          "close": "0000"
        }
      ],
      "formattedText": "Sunday:  Closed"
    },
    "monday": {
      "hours": [
        {
          "open": "0900",
          "close": "1700"
        }
      ],
      "formattedText": "Monday:  09:00 am - 05:00 pm"
    },
    "tuesday": {
      "hours": [
        {
          "open": "0900",
          "close": "1700"
        }
      ],
      "formattedText": "Tuesday:  09:00 am - 05:00 pm"
    },
    "wednesday": {
      "hours": [
        {
          "open": "0900",
          "close": "1500"
        },
        {
          "open": "1700",
          "close": "2000"
        }
      ],
      "formattedText": "Wednesday:  09:00 am - 03:00 pm, 05:00 pm - 08:00 pm"
    },
    "thursday": {
      "hours": [
        {
          "open": "0900",
          "close": "1700"
        }
      ],
      "formattedText": "Thursday:  09:00 am - 05:00 pm"
    },
    "friday": {
      "hours": [
        {
          "open": "0900",
          "close": "1700"
        }
      ],
      "formattedText": "Friday:  09:00 am - 05:00 pm"
    },
    "saturday": {
      "hours": [
        {
          "open": "0000",
          "close": "2400"
        }
      ],
      "formattedText": "Saturday:  Open 24 hr"
    }
  },
  "contactInfo": {
    "phone": "4125555555",
    "url": "https://www.itech.com"
  },
  "lastModified": "2020-01-14T17:29:20.999Z"
}
Last updated March 12, 2020.