Distance Isoline
A distance isoline (isodistance) is the area that can be reached within a given distance of travel along the road network. Distance isolines are time-independent: traffic is not used, but long-term road closures are respected, so the same request returns the same result whenever it is made. There are no departure, arrival, or traffic parameters. For reachability that accounts for traffic, use a Travel-Time Isoline.
Resource URL
Resource Information
| HTTP Methods | GET, POST |
| Request Formats | URL query parameters, JSON body |
| Response Formats | JSON |
| Authentication | Requires key query param |
| Rate Limited | Yes |
Direction
A request is either outbound or inbound, and exactly one of from or to must be supplied.
- Outbound: reachable from a location. Start at
from. The result is the area that can be reached by traveling away from that point. - Inbound: can get to a location. End at
to. The result is the area from which that point can be reached, honoring one-way streets and turn restrictions in the inbound direction.
A request with both from and to is rejected.
Request Parameters
| Request Parameter | Description | Required |
|---|---|---|
| key String | The API Key, which is needed to make requests to MapQuest services. | Yes |
| from Coordinates | The center point the isoline is calculated outward from. Accepted forms:
| Yes (or to) |
| to Coordinates | The center point the isoline is calculated inward to. Same accepted forms as from. | Yes (or from) |
| within Number collection | One or more distance limits, measured in unit, each producing an isoline polygon. For example, within=1,5 returns the 1 mile and 5 mile isolines. Fractional values such as 0.5 are accepted.Maximum: 5 values per request. Each value must be greater than 0. Maximum value: 620 miles (1,000 km). | Yes |
| unit String | The unit the within values are measured in.
mi | No |
| routeType String | Specifies the type of travel used to calculate the isoline. Acceptable values are:
fastest measures distance along the roads a driver would typically take, favoring highways, while shortest measures it along the most direct sensible route and so covers more area. For example, a 10 mile isoline from downtown Denver covers about 11% less area with fastest than with shortest.Default: fastest | No |
| quality String | Trades isoline precision against response time.
balanced | No |
| generalize Integer | Smooths the isoline by removing detail finer than this distance, in meters. 0 returns the full-resolution shape. Higher values result in fewer points and a coarser shape.Default: 0Maximum: 4294967295 | No |
Response Object
| Field | Description |
|---|---|
| from | The point the isoline was calculated from, as a latLng object, after snapping to the nearest road. Only present when from was supplied. |
| to | The point the isoline was calculated to, as a latLng object, after snapping to the nearest road. Only present when to was supplied. |
| isolines | A GeoJSON FeatureCollection. Contains one Feature per value in within, in the order requested. |
| isolines.features[].properties.within | The within value this polygon represents. |
| isolines.features[].properties.unit | The unit of within, echoing the request. |
| isolines.features[].geometry | A GeoJSON Polygon, or a MultiPolygon when the reachable area is disconnected (for example, separated by water with no ferry). Coordinates are [lng, lat] per the GeoJSON specification. Inner rings represent unreachable holes. |
| warnings | An array of non-fatal notices, each with a code and message. Present only when applicable. See Warning Codes. |
Warning Codes
| Code | Description |
|---|---|
locationSnapped | The from/to point was more than 100 meters from the nearest road and was snapped to it. |
Error Responses
Errors are returned as application/problem+json.
| Status | Description |
|---|---|
| 400 | A parameter is missing or invalid. errors lists each problem with a pointer to the parameter, such as #/within/1. |
| 422 | The from/to point could not be matched to a road. |
| 502 | The isoline could not be calculated. |
| 503 | The isoline service is temporarily unavailable. Please retry. |
Example Request
GET
Everything within a 5 mile drive of a transit station:
curl -X GET 'https://www.mapquestapi.com/isoline/v1/distance' \
--url-query 'key=YOUR_API_KEY' \
--url-query 'from=39.7536,-105.0002' \
--url-query 'within=5'500 m and 1 km walking isolines around downtown Denver:
curl -X GET 'https://www.mapquestapi.com/isoline/v1/distance' \
--url-query 'key=YOUR_API_KEY' \
--url-query 'from=39.7392,-104.9903' \
--url-query 'routeType=pedestrian' \
--url-query 'within=0.5,1' \
--url-query 'unit=km'Everywhere a hospital can be reached from within 10 miles (inbound isoline):
curl -X GET 'https://www.mapquestapi.com/isoline/v1/distance' \
--url-query 'key=YOUR_API_KEY' \
--url-query 'to=39.7444,-104.9407' \
--url-query 'within=10'POST
The same 500 m and 1 km walking isolines as above, as a JSON body with from as an object:
curl -X POST 'https://www.mapquestapi.com/isoline/v1/distance' \
--url-query 'key=YOUR_API_KEY' \
--json '{
"from": { "lat": 39.7392, "lng": -104.9903 },
"routeType": "pedestrian",
"within": [0.5, 1],
"unit": "km"
}'Example Response
{
"from": {
"latLng": {
"lat": 39.753600,
"lng": -105.000200
}
},
"isolines": {
"type": "FeatureCollection",
"features": [
{
"type": "Feature",
"properties": {
"within": 5,
"unit": "mi"
},
"geometry": {
"type": "Polygon",
"coordinates": [
[
[-105.0856, 39.7534],
[-105.0763, 39.7975],
[-105.0155, 39.8310],
[-104.9401, 39.8273],
[-104.9070, 39.7804],
[-104.9091, 39.7175],
[-104.9606, 39.6769],
[-105.0533, 39.6831],
[-105.0856, 39.7534]
]
]
}
}
]
}
}