Referring to Locations with Place IDs

A place ID is a textual identifier that uniquely identifies places such as businesses, landmarks, parks, and intersections. The length of the identifier can vary (there is no maximum length for Place IDs). For more information, see Google Map Place ID.

It is possible for the same place or location to have multiple unique place IDs and the IDs can change over time. Place IDs are exempt from the caching restrictions stated in Section 3.2.3(a) of the Google Maps Platform Terms of Service. You can therefore store place ID values for later use.

The new place ID support lets you refer to a location by using a place ID instead of lat/lng in your Cloud Fleet Routing requests. Using LatLng is still supported. You can even mix place ID and LatLng in the request. There are caching restrictions for LatLng, as stated in the Google Maps Platform Terms of Service. Google recommends that you start caching place IDs and using place IDs going forward.

Examples

This section shows you how to use Place IDs.

Example without Place IDs

The following JSON request uses LatLng to refer to locations. You can send the request by using the API Client Library for Python.

{
  "parent": "projects/${YOUR_GCP_PROJECT_ID}",
  "model": {
    "shipments": [
      {
        "deliveries": [
          {
            "arrivalLocation": {
              "latitude": 48.880942,
              "longitude": 2.323866
            },
            "duration": "250s",
            "timeWindows": [
              {
                "endTime": "1970-01-01T01:06:40Z",
                "startTime": "1970-01-01T00:50:00Z"
              }
            ]
          }
        ],
        "loadDemands": {
          "weight":
            {
              "amount": 10
            }
        },
        "pickups": [
          {
            "arrivalLocation": {
              "latitude": 48.874507,
              "longitude": 2.30361
            },
            "duration": "150s",
            "timeWindows": [
              {
                "endTime": "1970-01-01T00:33:20Z",
                "startTime": "1970-01-01T00:16:40Z"
              }
            ]
          }
        ]
      },
      {
        "deliveries": [
          {
            "arrivalLocation": {
              "latitude": 48.88094,
              "longitude": 2.323844
            },
            "duration": "251s",
            "timeWindows": [
              {
                "endTime": "1970-01-01T01:06:41Z",
                "startTime": "1970-01-01T00:50:01Z"
              }
            ]
          }
        ],
        "loadDemands": {
          "weight":
            {
              "amount": 20
            }
        },
        "pickups": [
          {
            "arrivalLocation": {
              "latitude": 48.880943,
              "longitude": 2.323867
            },
            "duration": "151s",
            "timeWindows": [
              {
                "endTime": "1970-01-01T00:33:21Z",
                "startTime": "1970-01-01T00:16:41Z"
              }
            ]
          }
        ]
      }
    ],
    "vehicles": [
      {
       "loadLimits": {
          "weight": {
            "maxLoad": 50
          }
        },
        "endLocation": {
          "latitude": 48.86311,
          "longitude": 2.341205
        },
        "startLocation": {
          "latitude": 48.863102,
          "longitude": 2.341204
        }
      },
      {
        "loadLimits": {
          "weight": {
            "maxLoad": 60
          }
        },
        "endLocation": {
          "latitude": 48.86312,
          "longitude": 2.341215
        },
        "startLocation": {
          "latitude": 48.863112,
          "longitude": 2.341214
        }
      }
    ]
  }
}

Response

When you send the request, it returns the following response in a proto format.

routes {
  vehicle_start_time {
    seconds: 131
  }
  vehicle_end_time {
    seconds: 4534
  }
  visits {
    is_pickup: true
    start_time {
      seconds: 1000
    }
    detour {
    }
    arrival_loads {
      type_: "weight"
    }
  }
  visits {
    shipment_index: 1
    is_pickup: true
    start_time {
      seconds: 1655
    }
    detour {
      seconds: 725
    }
    arrival_loads {
      type_: "weight"
      value: 10
    }
  }
  visits {
    start_time {
      seconds: 3000
    }
    detour {
      seconds: 1345
    }
    arrival_loads {
      type_: "weight"
      value: 30
    }
  }
  visits {
    shipment_index: 1
    start_time {
      seconds: 3523
    }
    detour {
      seconds: 1444
    }
    arrival_loads {
      type_: "weight"
      value: 20
    }
  }
  travel_steps {
    duration {
      seconds: 869
    }
    distance_meters: 4243.0
  }
  travel_steps {
    duration {
      seconds: 505
    }
    distance_meters: 2479.0
  }
  travel_steps {
    duration {
    }
  }
  travel_steps {
    duration {
      seconds: 273
    }
    distance_meters: 986.0
  }
  travel_steps {
    duration {
      seconds: 760
    }
    distance_meters: 3099.0
  }
  vehicle_detour {
    seconds: 4403
  }
  end_loads {
    type_: "weight"
  }
  transitions {
    travel_duration {
      seconds: 869
    }
    travel_distance_meters: 4243.0
    loads {
      type_: "weight"
    }
  }
  transitions {
    travel_duration {
      seconds: 505
    }
    travel_distance_meters: 2479.0
    loads {
      type_: "weight"
      value: 10
    }
  }
  transitions {
    travel_duration {
    }
    loads {
      type_: "weight"
      value: 30
    }
  }
  transitions {
    travel_duration {
      seconds: 273
    }
    travel_distance_meters: 986.0
    loads {
      type_: "weight"
      value: 20
    }
  }
  transitions {
    travel_duration {
      seconds: 760
    }
    travel_distance_meters: 3099.0
    loads {
      type_: "weight"
    }
  }
}
routes {
  vehicle_index: 1
  vehicle_start_time {
  }
  vehicle_end_time {
  }
  vehicle_detour {
  }
}

Example with Place IDs

The following example shows how to use Place IDs in the previous request.

In the previous request, we use arrival_location for shipment and start_location for vehicle.

"arrival_location": {
  "latitude": 48.880942,
  "longitude": 2.323866
}
"start_location": {
  "latitude": 48.863102,
  "longitude": 2.341204
}

In the new request, we use arrival_waypoint for shipment and start_waypoint for vehicle.

"arrival_waypoint": {
  "place_id": "ChIJD7fiBh9u5kcRYJSMaMOCCwQ"
}
"start_waypoint": {
  "place_id": "ChIJPStI0CVu5kcRUBqUaMOCCwU"
}

In a single pickup/delivery/vehicle, you cannot use both LatLng and Place ID for the same type of location. For example, in the pickup, if you use both arrival_location and arrival_waypoint, you will get validation error.

Request

Here's the full request.

{
  "parent": "projects/${YOUR_GCP_PROJECT_ID}",
  "model": {
    "shipments": [
      {
        "deliveries": [
          {
            "arrival_waypoint": {
              "place_id": "ChIJZeKEs7Rv5kcR4JyAbXpeMnQ"
            },
            "duration": "250s",
            "timeWindows": [
              {
                "endTime": "1970-01-01T01:06:40Z",
                "startTime": "1970-01-01T00:50:00Z"
              }
            ]
          }
        ],
        "loadDemands": {
          "weight":
            {
              "amount": 10
            }
         },
        "pickups": [
          {
            "arrival_waypoint": {
              "place_id": "ChIJn5SPq8Fv5kcR80LIq_ydEvc"
            },

            "duration": "150s",
            "timeWindows": [
              {
                "endTime": "1970-01-01T00:33:20Z",
                "startTime": "1970-01-01T00:16:40Z"
              }
            ]
          }
        ]
      },
      {
        "deliveries": [
          {
            "arrival_waypoint": {
              "place_id": "ChIJZeKEs7Rv5kcR4JyAbXpeMnQ"
            },
            "duration": "251s",
            "timeWindows": [
              {
                "endTime": "1970-01-01T01:06:41Z",
                "startTime": "1970-01-01T00:50:01Z"
              }
            ]
          }
        ],
        "loadDemands": {
          "weight":
            {
              "amount": 20
            }
         },
        "pickups": [
          {
            "arrival_waypoint": {
              "place_id": "ChIJZeKEs7Rv5kcR4JyAbXpeMnQ"
            },
            "duration": "151s",
            "timeWindows": [
              {
                "endTime": "1970-01-01T00:33:21Z",
                "startTime": "1970-01-01T00:16:41Z"
              }
            ]
          }
        ]
      }
    ],
    "vehicles": [
      {
        "loadLimits": {
          "weight": {
            "maxLoad": 50
          }
        },
        "end_waypoint": {
              "place_id": "ChIJaypPuyNu5kcRdB3vQE1WNV0"
            },
        "start_waypoint": {
          "place_id": "ChIJaypPuyNu5kcRdB3vQE1WNV0"
        }
      },
      {
         "loadLimits": {
          "weight": {
            "maxLoad": 60
          }
        },
        "end_waypoint": {
              "place_id": "ChIJiV-buiNu5kcRMlUKLbraF4U"
        },
        "start_waypoint": {
          "place_id": "ChIJiV-buiNu5kcRMlUKLbraF4U"
        }
      }
    ]
  }
}

You can send the request by using the API Client Library for Python.

Response

Here's the response.

routes {
  vehicle_start_time {
    seconds: 131
  }
  vehicle_end_time {
    seconds: 4534
  }
  visits {
    is_pickup: true
    start_time {
      seconds: 1000
    }
    detour {
    }
    arrival_loads {
      type_: "weight"
    }
  }
  visits {
    shipment_index: 1
    is_pickup: true
    start_time {
      seconds: 1655
    }
    detour {
      seconds: 725
    }
    arrival_loads {
      type_: "weight"
      value: 10
    }
  }
  visits {
    start_time {
      seconds: 3000
    }
    detour {
      seconds: 1345
    }
    arrival_loads {
      type_: "weight"
      value: 30
    }
  }
  visits {
    shipment_index: 1
    start_time {
      seconds: 3523
    }
    detour {
      seconds: 1444
    }
    arrival_loads {
      type_: "weight"
      value: 20
    }
  }
  travel_steps {
    duration {
      seconds: 869
    }
    distance_meters: 4243.0
  }
  travel_steps {
    duration {
      seconds: 505
    }
    distance_meters: 2479.0
  }
  travel_steps {
    duration {
    }
  }
  travel_steps {
    duration {
      seconds: 273
    }
    distance_meters: 986.0
  }
  travel_steps {
    duration {
      seconds: 760
    }
    distance_meters: 3099.0
  }
  vehicle_detour {
    seconds: 4403
  }
  end_loads {
    type_: "weight"
  }
  transitions {
    travel_duration {
      seconds: 869
    }
    travel_distance_meters: 4243.0
    loads {
      type_: "weight"
    }
  }
  transitions {
    travel_duration {
      seconds: 505
    }
    travel_distance_meters: 2479.0
    loads {
      type_: "weight"
      value: 10
    }
  }
  transitions {
    travel_duration {
    }
    loads {
      type_: "weight"
      value: 30
    }
  }
  transitions {
    travel_duration {
      seconds: 273
    }
    travel_distance_meters: 986.0
    loads {
      type_: "weight"
      value: 20
    }
  }
  transitions {
    travel_duration {
      seconds: 760
    }
    travel_distance_meters: 3099.0
    loads {
      type_: "weight"
    }
  }
}
routes {
  vehicle_index: 1
  vehicle_start_time {
  }
  vehicle_end_time {
  }
  vehicle_detour {
  }
}