Skip to content

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 ​

https://www.mapquestapi.com/isoline/v1/distance

Resource Information ​

HTTP MethodsGET, POST
Request FormatsURL query parameters, JSON body
Response FormatsJSON
AuthenticationRequires key query param
Rate LimitedYes

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 ParameterDescriptionRequired
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:
  • lat,lng string - 39.7392,-104.9903
  • {lat, lng} object - {"lat": 39.7392, "lng": -104.9903}
  • {lat, lon} object - {"lat": 39.7392, "lon": -104.9903}
Use the Geocoding API to convert an address to coordinates first.
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 - Miles
  • km - Kilometers
Default: mi
No
routeType
String
Specifies the type of travel used to calculate the isoline. Acceptable values are:
  • fastest - Driving, optimized for quickest travel time.
  • shortest - Driving, optimized for shortest distance.
  • pedestrian - Walking. Avoids limited access roads; ignores turn restrictions.
  • bicycle - Will only use roads on which bicycling is appropriate.
For driving, 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.
  • fast - Lowest precision, fastest response.
  • balanced - Reasonable precision and response time.
  • high - Highest precision, slowest response.
Default: 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: 0
Maximum: 4294967295
No

Response Object ​

FieldDescription
fromThe point the isoline was calculated from, as a latLng object, after snapping to the nearest road. Only present when from was supplied.
toThe point the isoline was calculated to, as a latLng object, after snapping to the nearest road. Only present when to was supplied.
isolinesA GeoJSON FeatureCollection. Contains one Feature per value in within, in the order requested.
isolines.features[].properties.withinThe within value this polygon represents.
isolines.features[].properties.unitThe unit of within, echoing the request.
isolines.features[].geometryA 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.
warningsAn array of non-fatal notices, each with a code and message. Present only when applicable. See Warning Codes.

Warning Codes ​

CodeDescription
locationSnappedThe 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.

StatusDescription
400A parameter is missing or invalid. errors lists each problem with a pointer to the parameter, such as #/within/1.
422The from/to point could not be matched to a road.
502The isoline could not be calculated.
503The isoline service is temporarily unavailable. Please retry.

Example Request ​

GET ​

Everything within a 5 mile drive of a transit station:

bash
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:

bash
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):

bash
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:

bash
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 ​

json
{
  "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]
            ]
          ]
        }
      }
    ]
  }
}