POST /confirm-move-eligibility

This endpoint is used to determine whether the provided coordinates for a pickup or delivery location fall within an active Hopdrive serviceable area for a rooftop. It accepts latitude and longitude coordinates for both pickup and delivery locations and checks if either or both locations fall within a valid rooftop service area.

Example Request

POST /v1/confirm-move-eligibility
{
  "pickup_location" : {
    "name": "The White House",
    "address_one": "1600 Pennsylvania Ave NW",
    "city": "Washington",
    "state": "DC",
    "zip": "20500",
    "latitude": 38.8977,
    "longitude": -77.0365
  },
  "delivery_location" : {
    "name": "The Capitol",
    "address_one": "East Capitol St NE & First St SE",
    "city": "Washington",
    "state": "DC",
    "zip": "20004",
    "latitude": 38.8899,
    "longitude": -77.0091
  }
  "drive_miles": 2.5,
}

Body Params

Field	Type	Required?	Description
pickup_location	Object	Required	Address object containing pickup location details. See Address Object Structure below.
delivery_location	Object	Required	Address object containing delivery location details. See Address Object Structure below.
drive_miles	Number	Optional	The expected driving distance in miles between pickup and delivery locations. If provided, must be within the configured maximum drive distance limit. Used for pre-validation of move feasibility.

Address Object Structure

Each address object (pickup_location and delivery_location) supports the following fields:

Field	Type	Required?	Description
latitude	Number	Required*	Latitude coordinate for the location. Must be a valid number between -90 and 90 degrees. Cannot be exactly 0 when longitude is also 0 (indicates invalid/default coordinates).
longitude	Number	Required*	Longitude coordinate for the location. Must be a valid number between -180 and 180 degrees. Cannot be exactly 0 when latitude is also 0 (indicates invalid/default coordinates).
name	String	Optional	Name or label for the location (e.g., "Customer Home", "Service Center").
full_address	String	Optional	Complete address string. If provided, individual address components (address_one, city, state, zip) are not required.
address_one	String	Required**	Primary street address of the location.
address_two	String	Optional	Secondary address information (apartment, suite, etc.).
city	String	Required**	City name for the address.
state	String	Required**	State abbreviation for the address.
zip	String	Required**	ZIP/postal code for the address.

Required Field Notes:

* GPS coordinates (latitude/longitude) are required unless complete address information is provided
** Address components (address_one, city, state, zip) are required unless valid GPS coordinates or full_address is provided

Drive Distance Validation

When the optional drive_miles parameter is provided, the endpoint validates that the specified distance is within acceptable limits:

Validation Rules:

Maximum Distance: The drive distance must not exceed the configured maximum drive distance limit
Pre-validation: Used to pre-validate move feasibility before processing GPS coordinates or addresses
Fallback: If drive_miles is not provided, the system will calculate the actual driving distance using Google Maps API when valid addresses are available

If the provided drive_miles exceeds the maximum allowed distance, the endpoint will return a 406 error before proceeding with location validation.

Example Response

The endpoint can return 200, 403, 406, or 500 responses. If the pickup or delivery location is within the serviceable radius of a rooftop, the response will return the rooftop id, name, serviceable radius, and center coordinates. If the pickup or delivery location is not within the serviceable radius of any rooftop, the response will return a 406 error.

200 /v1/confirm-move-eligibility
{
  "rooftop": {
    "id": 70,
    "name": "Ben's auto world",
    "serviceable_radius_miles": 200,
    "serviceable_radius_by_pickup": true,
    "serviceable_radius_by_delivery": true,
    "center": {
      "latitude": 37.5198999,
      "longitude": -77.4588816
    },
    "workflowsets": [
      {
        "id": 455,
        "name": "Standard Concierge",
        "description": "Standard pickup and delivery",
        "type": "standard",
        "active_contracts": [
          {
            "begin_date": "2025-02-28T05:09:00+00:00",
            "end_date": "2030-02-28T20:45:00+00:00",
            "mileage_bands": [
              {
                "distance_start": 0,
                "distance_end": 999,
                "type": "flatPlusPer",
                "class_1_rate": 2.25,
                "class_2_rate": 2.25,
                "class_3_rate": 2.25,
                "class_4_rate": 3,
                "class_5_rate": 3,
                "class_6_rate": 3,
                "class_1_flat_rate": 50,
                "class_2_flat_rate": 50,
                "class_3_flat_rate": 50,
                "class_4_flat_rate": 50,
                "class_5_flat_rate": 50,
                "class_6_flat_rate": 50,
                "class": "stranded"
              }
            ]
          }
        ]
      },
      {
        "id": 287,
        "name": "Accelerated Concierge",
        "description": "Priority same-day pickup and delivery",
        "type": "accelerated",
        "active_contracts": [
          {
            "begin_date": "2025-02-24T05:00:00+00:00",
            "end_date": "2027-03-01T05:00:00+00:00",
            "mileage_bands": [
              {
                "distance_start": 0,
                "distance_end": 999,
                "type": "flatPlusPer",
                "class_1_rate": 3.50,
                "class_2_rate": 3.50,
                "class_3_rate": 3.50,
                "class_4_rate": 4,
                "class_5_rate": 4,
                "class_6_rate": 4,
                "class_1_flat_rate": 50,
                "class_2_flat_rate": 50,
                "class_3_flat_rate": 50,
                "class_4_flat_rate": 50,
                "class_5_flat_rate": 50,
                "class_6_flat_rate": 50,
                "class": "stranded"
              }
            ]
          }
        ]
      }
    ]
  },
  "distance_to_rooftop_center": {
    "pickup": {
      "meters": 157763,
      "miles": 98
    },
    "delivery": {
      "meters": 157500,
      "miles": 98
    }
  },
  "pickup_location": {
    "latitude": 38.8977,
    "longitude": -77.0365,
    "used_coords": {
      "latitude": 38.8977,
      "longitude": -77.0365
    }
  },
  "delivery_location": {
    "latitude": 38.8899,
    "longitude": -77.0091,
    "used_coords": {
      "latitude": 38.8899,
      "longitude": -77.0091
    }
  },
  "methodology": "coords",
  "mapsDataObj": null
}

Response Fields

Field	Type	Description
rooftop	Object	The nearest serviceable rooftop matching the provided locations.
rooftop.id	Number	Rooftop identifier.
rooftop.name	String	Rooftop display name.
rooftop.serviceable_radius_miles	Number	The configured serviceable radius in miles.
rooftop.serviceable_radius_by_pickup	Boolean	Whether the pickup location is checked against the serviceable radius.
rooftop.serviceable_radius_by_delivery	Boolean	Whether the delivery location is checked against the serviceable radius.
rooftop.center	Object	The center coordinates of the rooftop (`latitude`, `longitude`).
rooftop.workflowsets	Array	Pricing workflow sets associated with the rooftop.
rooftop.workflowsets[].active_contracts	Array	Currently active rate contracts.
rooftop.workflowsets[].active_contracts[].mileage_bands	Array	Mileage-based pricing bands. Each band defines rates per vehicle class for a distance range.
distance_to_rooftop_center	Object	Distance from the pickup and delivery locations to the rooftop center, in both meters and miles.
pickup_location	Object	Echo of the submitted pickup location, plus `used_coords` (when coords methodology) or `used_address` (when addresses methodology).
delivery_location	Object	Echo of the submitted delivery location, plus `used_coords` or `used_address`.
methodology	String	`"coords"` if GPS coordinates were used directly, `"addresses"` if addresses were geocoded to coordinates.
mapsDataObj	Object\|null	Geocoded coordinate data when address methodology was used, otherwise `null`.

Error Responses

403

The request is not authorized.

406

The pickup or delivery location is not within the serviceable radius of any rooftop, or the provided GPS coordinates are invalid.

Serviceable Area Error:

406 /v1/confirm-move-eligibility
{
    "errors": [
        {
            "type": "api_error",
            "code": "address_invalid",
            "message": "Pickup or delivery not within serviceable radius of any rooftop. No serviceable rooftops found",
            "doc_url": "https://api.hopdrive.com/docs/error-codes#address_invalid"
        }
    ]
}

Invalid Drive Distance Error (when drive_miles exceeds the maximum allowed distance):

406 /v1/confirm-move-eligibility
{
    "errors": [
        {
            "type": "api_error",
            "code": "address_invalid",
            "message": "Drive miles is out of range. Maximum drive distance is 500 miles",
            "doc_url": "https://api.hopdrive.com/docs/error-codes#address_invalid"
        }
    ]
}

Invalid Address Error (when coordinates fail validation and no valid addresses are provided):

406 /v1/confirm-move-eligibility
{
    "errors": [
        {
            "type": "api_error",
            "code": "address_invalid",
            "message": "Invalid pickup address",
            "doc_url": "https://api.hopdrive.com/docs/error-codes#address_invalid"
        }
    ]
}

500

An error occurred while processing the request.

Example Request​

Body Params​

Address Object Structure​

Drive Distance Validation​

Example Response​

Response Fields​

Error Responses​

403​

406​

500​