GuidesAPI Reference
API Reference

Calculate isolines via POST

post
https://isoline.router.hereapi.com/v8/isolines

Retrieves a list of polylines that captures the approximate reachable area from the specified center point constrained by the provided parameters.

At the moment, only select parameters are permitted in the POST payload. In particular, those parameters that due to request size may be limited in the query string. See the request body section below. These parameters can be provided either in the query string or in the POST body. All other parameters can only be provided in the query string at the moment.

Query Params
range
object
required

Specifies the range of values to be included in the isoline.

  • Range[type] : Specifies the type of range. Possible Values:
    • distance with units in meters
    • time with units in seconds
    • consumption with units in Watt-hours (Wh) for EV, or milliliters(ml) or grams(gms) for fuel-based vehicles, depending on fuel[type]
  • Range[values] : A comma-separated list of ranges. The unit is defined by the type parameter.
string
enum
required

Mode of transport to be used for the calculation of the isolines.

Note: bicycle, bus and privateBus modes are currently provided as Beta, with limited functionality. Please refer to the Developer Guide for more details here.

string

Center of the isoline request. The Isoline(s) will cover the region which can be reached from this point within given range. It cannot be used in combination with destination or arrivalTime parameter.

Format

Format: Place[WaypointOptions]

  • Place: {lat},{lng}[PlaceOptions]
  • PlaceOptions: ;option1=value1;option2=value2...
  • WaypointOptions: !option1=value1!option2=value2...

A waypoint consists of:

  • Exactly one place
  • Optional settings for the place
  • Optional settings for the waypoint itself

Supported place options

  • course: int, degrees clock-wise from the north. Indicates the desired direction from the place. For example, 90 indicating east. Often combined with radius and/or minCourseDistance

  • sideOfStreetHint: {lat},{lng}. Indicates the side of the street that should be used. For example, if the location is to the left of the street, the router will prefer using that side in case the street has dividers. For example, 52.511496,13.304140;sideOfStreetHint=52.512149,13.304076 indicates that the north side of the street should be preferred. This option is required, if matchSideOfStreet is set to always. Option cannot be combined with radius, radiusPenalty or snapRadius.

  • displayLocation: {lat},{lng}. Indicates the physical location of the POI. It is different from the originalLocation and location which are generally expected to be on the navigable road network, i.e., on segments.

  • matchSideOfStreet: enum [always, onlyIfDivided]. Specifies how the location set by sideOfStreetHint should be handled. Requires sideOfStreetHint to be specified as well.

    • always : Always prefer the given side of street.
    • onlyIfDivided: Only prefer using the side of street set by sideOfStreetHint in case the street has dividers. This is the default behavior.

  • nameHint: string. Causes the router to look for the place with the most similar name. The typical examples include: North being used to differentiate between interstates I66 North and I66 South, Downtown Avenue being used to correctly select a residental street.

    Empty string values are ignored.

  • radius: int, meters. Sets the radius within which all locations are considered equally eligible for selection as waypoints. Typical use cases include scenarios with imprecise coordinates or user input provided on low resolution map displays. The value is capped at 200 meters. Setting a higher value doesn't return an error. Can't be used with snapRadius.

  • radiusPenalty: int, percentage 0-1000. Used in conjunction of radius parameter. Router will match the waypoint, within the specified radius and penalize candidates according to air distance to the waypoint. Penalty is proportional to given percentage, 100 being just cost of air distance and 200 double. Currently works only for pedestrian/bicycle routes. Alpha: This parameter is in development. It may not be stable and is subject to change.

  • snapRadius: int, meters. Sets the radius within which waypoints are matched to the most "significant" place. Candidates for matching are sorted in the order of significance which is based on the visibility on a zoomed-out map. A highway is considered more significant than a national road, while a national road is more significant than a city road. Typical use case - selecting waypoints on a zoomed-out view of a map on a drag-and-drop interface, where only significant roads are visible. A big enough radius allows to match waypoints to such roads. Can't be used with radius or radiusPenalty parameters.

  • minCourseDistance: int, meters. Instructs the routing service to try to find a route that avoids actions for the indicated distance. For example, if the origin is determined by a moving vehicle, the user might not have time to react to early actions. Values greater than 2000 meters will be capped at 2000 meters.

  • segmentIdHint: string. Causes the router to try and match to the specified segment. Waypoint coordinates need to be on the segment, otherwise waypoint will be matched ignoring the segment hint This parameter can be used when the waypoint is too close to more than one segment to force matching to a specific one.

  • onRoadThreshold: int, meters. allows specifying a distance within which the waypoint could be considered as being on a highway/bridge/tunnel/sliproad. Within this threshold, the attributes of the segments do not impact the matching. Outside the threshold only segments which aren't one of highway/bridge/tunnel/sliproad can be matched.

Notes

  • Non-structural reserved characters in options' values need to be properly percent-encoded. Please refer to the developers' guide for more details.
date-time

Specifies the time of departure as defined by either date-time or full-date T partial-time in RFC 3339, section 5.6 (for example, 2019-06-24T01:23:45). The requested time is converted to the local time at origin. When the optional timezone offset is not specified, time is assumed to be local. If neither departureTime or arrivalTime are specified, current time at departure location will be used if origin is specified. It cannot be used in combination with destination parameter. All Time values in the response are returned in the timezone of each location.

string

Center of the isoline request. The Isoline(s) will cover the region within the specified range that can reach this point. It cannot be used in combination with origin or departureTime parameter.

For a description of the format and options for this parameter, please refer to the description of the origin parameter.

date-time

Specifies the time of arrival as defined by either date-time or full-date T partial-time in RFC 3339, section 5.6 (for example, 2019-06-24T01:23:45). The requested time is converted to the local time at destination. When the optional timezone offset is not specified, time is assumed to be local. If neither departureTime or arrivalTime are specified, current time at arrival location will be used if destination is specified. It cannot be used in combination with origin parameter. All Time values in the response are returned in the timezone of each location.

string
enum
Defaults to fast

Specifies which optimization is applied during the calculation.

  • fast: Route calculation from start to destination optimized by travel time. In many cases, the route returned by fast mode may not be the route with the fastest possible travel time. For example, the routing service may favor a route that remains on a highway, even if a faster travel time can be achieved by taking a detour or shortcut through an inconvenient side road.
  • short: Route calculation from start to destination disregarding any speed information. In this mode, the distance of the route is minimized, while keeping the route sensible. This includes, for example, penalizing turns. Because of that, the resulting route will not necessarily be the one with minimal distance.

Notes:

  • The following Transport modes only support fast routingMode
    • bicycle
    • bus
    • pedestrian
    • privateBus
    • scooter
    • taxi
Allowed:
shape
object

A struct used to control the shape of the returned isolines.

  • shape[maxPoints]: Limits the number of points in the resulting isoline geometry. If the isoline consists of multiple components, the sum of points from all components is considered. This parameter doesn't affect performance. Look at optimizeFor parameter to optimize for performance.
string
enum
Defaults to balanced

Specifies how isoline calculation is optimized.

  • quality: calculation of isoline focuses on quality, that is, the graph used for isoline calculation has higher granularity generating an isoline that is more precise.
  • performance: calculation of isoline is performance-centric, quality of isoline is reduced to provide better performance.
  • balanced: calculation of isoline takes a balanced approach averaging between quality and performance.
Allowed:
avoid
object

Avoid roads that violate certain features of road network or that go through user-specified areas, segments, or zones.

exclude
object

User-specified properties that need to be strictly excluded during route calculation.

allow
object

Explicitly allow features that require users to opt in.

truck
object
deprecated

Truck-specific parameters.

NOTE: The attribute truck is deprecated and should be replaced with vehicle.

vehicle
object

Vehicle-specific parameters.

string
Defaults to empirical

Specifies which of the EV consumption models is being used. See the ev parameter for details on the models.

  • empirical
  • physical

Alpha: Physical consumption model is in development. It may not be stable and is subject to change.

ev

EV parameters to be used for calculating consumption and for calculating isolines for EV.

There are two consumption models (empirical, physical). Set the consumptionModel parameter to choose which model to use.

Required empirical model properties:

  • freeFlowSpeedTable

Required physical model properties:

  • driveEfficiency
  • recuperationEfficiency

When using the physical model, certain properties of the vehicle parameter are also required (see documentation for the vehicle parameter for more details):

  • rollingResistanceCoefficient
  • airDragCoefficient
  • currentWeight
  • frontalArea or combination of width and height
fuel
object

Disclaimer: This parameter is currently in beta release, and is therefore subject to breaking changes.

Fuel parameters to be used for calculating consumption and consumption-based isolines for fuel-based vehicles.

Attributes:

  • type
  • freeFlowSpeedTable
  • trafficSpeedTable
  • additionalConsumption
  • ascent
string

Specify new base speed for segment by value. Affects route selection and the ETA. Cannot increase base speed on segment.

taxi
object

Taxi-specific parameters.

  • allowDriveThroughTaxiRoads: Specifies if a vehicle is allowed to drive through taxi-only roads and lanes. Even if this option is set to false, the vehicle is still allowed on taxi-only roads at the start of the route and at the destination.
traffic
object

Traffic specific parameters.

string

A list of up to six billing tags, separated by the + sign.

This parameter provides a way to track your platform usage. For details, refer to the Cost Management Developer Guide section on Billing Tags

Body Params
avoid
object

Avoid routes that violate certain features of road network or that go through user-specified geographical bounding boxes.

For the general description of the functionality please refer to the avoid parameter of the query string.

Passing parameters in the POST body is suggested when the length of the parameters exceeds the limitation of the GET request.

exclude
object

User-specified properties that need to be strictly excluded during route calculation.

For the general description of the functionality please refer to the exclude parameter of the query string.

Passing parameters in the POST body is suggested when the length of the parameters exceeds the limitation of the GET request.

maxSpeedOnSegment
array of objects

Segments with restrictions on maximum baseSpeed.

For the general description of the functionality please refer to the maxSpeedOnSegment parameter of the query string.

Passing parameters in the POST body is suggested when the length of the parameters exceeds the limitation of the GET request.

Example of a parameter value excluding two segments:

[
  {
    "segment": "here:cm:segment:207551710#+",
    "speed": 10
  },
  {
    "segment": "here:cm:segment:76771992",
    "speed": 1
  }
]

Notes:

  • Maximum number of penalized segments in one request cannot be greater than 1000. "penalized segments" refer to segments that have a restrictions on maximum baseSpeed with maxSpeedOnSegment or avoided with avoid[segments].
  • In case the same segment is penalized multiple times through values provided in the query string and/or the POST body, then the most restrictive value will be applied.
maxSpeedOnSegment
Headers
string

User-provided token that can be used to trace a request or a group of requests sent to the service.

Responses

Updated 29 days ago

Language
Credentials
Response 
Click Try It! to start a request and see the response here! Or choose an example:
application/json
Updated 29 days ago