GET /locations

Look up HopDrive locations your application is authorized to see. Use these endpoints to discover a location's HopDrive id — for example when you want to pass pickup_location_id / delivery_location_id to GET /appointments/availability instead of an address string, or to confirm which saved location an address resolved to.

Results are always scoped to the rooftops your bearer token authorizes; you will never see another dealer's locations.

GET /locations

Returns an array of locations matching the supplied query params. With no filters it returns every location your token can access (paginated).

Example Request

List locations for a rooftop

curl --request GET \
  --url 'https://api.hopdrive.com/v1/locations?customer_id=1234&search=Mulberry' \
  --header 'Authorization: Bearer <your token>'

Query Params

All query params are optional. Filters combine with AND.

Field	Type	Description
customer_id	Number	Restrict to a single rooftop. Must be a rooftop your bearer token authorizes, else ACCESS_DENIED.
region_id	Number	Restrict to locations in a given HopDrive region.
type	String	Restrict to a location type (e.g. customer, consumer residential, consumer business).
active	Boolean	true/1 returns only active locations; false/0 returns only inactive ones. Omit to return both.
search	String	Partial, case-insensitive match against the location name or full address. Handy for finding an address.
limit	Number	Max rows to return. Default 100, capped at 500.
offset	Number	Number of rows to skip, for pagination. Default 0.

Example Response

200 /v1/locations

{
  "locations": [
    {
      "id": 9001,
      "customer_id": 1234,
      "name": "210 S Mulberry St",
      "nickname": null,
      "address": "210 S Mulberry St, Richmond, VA 23220",
      "address_one": "210 S Mulberry St",
      "address_two": null,
      "city": "Richmond",
      "state": "VA",
      "zip": "23220",
      "latitude": 37.5407,
      "longitude": -77.4665,
      "place_id": "ChIJ...",
      "region_id": 12,
      "type": "consumer residential",
      "timezone": "America/New_York",
      "active": 1,
      "email": null,
      "phone": null,
      "createdat": "2026-05-01T14:22:10.000Z",
      "updatedat": "2026-05-01T14:22:10.000Z"
    }
  ]
}

GET /locations/:id

Fetch a single location by its HopDrive id.

Example Request

Get a location by id

curl --request GET \
  --url 'https://api.hopdrive.com/v1/locations/9001' \
  --header 'Authorization: Bearer <your token>'

Example Response

200 /v1/locations/9001

{
  "id": 9001,
  "customer_id": 1234,
  "name": "210 S Mulberry St",
  "nickname": null,
  "address": "210 S Mulberry St, Richmond, VA 23220",
  "address_one": "210 S Mulberry St",
  "address_two": null,
  "city": "Richmond",
  "state": "VA",
  "zip": "23220",
  "latitude": 37.5407,
  "longitude": -77.4665,
  "place_id": "ChIJ...",
  "region_id": 12,
  "type": "consumer residential",
  "timezone": "America/New_York",
  "active": 1,
  "email": null,
  "phone": null,
  "createdat": "2026-05-01T14:22:10.000Z",
  "updatedat": "2026-05-01T14:22:10.000Z"
}

Response Fields

Field	Type	Description
id	Number	HopDrive location ID. This is the value to pass to other endpoints.
customer_id	Number	The rooftop that owns this location.
name	String	Display name (often the street address or a business name).
nickname	String	Optional dealer-assigned nickname. May be null.
address	String	Full formatted address.
address_one	String	Street address line.
address_two	String	Suite / unit / PO box line. May be null.
city	String	City.
state	String	State.
zip	String	Postal code.
latitude	Number	Geocoded latitude.
longitude	Number	Geocoded longitude.
place_id	String	Google Place ID, when known.
region_id	Number	HopDrive region this location falls in. May be null if not yet assigned.
type	String	Location type.
timezone	String	IANA timezone of the location.
active	Number	1 if active, 0 if inactive.
email	String	Optional contact email. May be null.
phone	String	Optional contact phone. May be null.
createdat	String	ISO 8601 UTC creation timestamp.
updatedat	String	ISO 8601 UTC last-update timestamp.

Error Responses

HTTP	Code	Cause
400	REQUEST_INVALID	A query param has the wrong type, or the :id path segment is not a number.
401	ACCESS_DENIED	Missing / invalid bearer token, or a customer_id filter the token does not authorize.
404	REQUEST_INVALID	No location with that id is visible to your bearer token.
500	UNKNOWN	Unexpected server error.