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
{
"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_milesis 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.
{
"rooftop": {
"id": 139,
"name": "Test Rooftop - Richmond Market",
"serviceable_radius_miles": 100,
"serviceable_radius_by_pickup": true,
"serviceable_radius_by_delivery": true,
"center": {
"latitude": 38.889810,
"longitude": -77.050284
}
},
"distance_to_rooftop_center": {
"pickup": {
"meters": 1530,
"miles": 0.95
},
"delivery": {
"meters": 2760,
"miles": 1.71
}
},
"pickup_location": {
"name": "The White House",
"address_one": "1600 Pennsylvania Ave NW",
"city": "Washington",
"state": "DC",
"zip": "20500",
"latitude": 38.8977,
"longitude": -77.0365,
"is_within_supported_region": true
},
"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,
"is_within_supported_region": true
}
}
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:
{
"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):
{
"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 GPS Coordinates Error (when coordinates fail validation and no valid addresses are provided):
{
"errors": [
{
"type": "api_error",
"code": "address_invalid",
"message": "Drive miles is out of range",
"doc_url": "https://api.hopdrive.com/docs/error-codes#address_invalid"
}
]
}
500
An error occurred while processing the request.