The Autohive OpenRouteService integration connects you to the OpenRouteService API. Your agent can:

  • Geocode addresses. Turn an address or place name into map coordinates. New Zealand is the default.
  • Draw drive-time areas. Get one or more areas you can reach from one point in a set time. Each area is called an isochrone. You get the result as inline data or as a file.
  • Compare travel times. Get driving times, and optional distances, for many start and end points in one request.

The map shapes use GeoJSON. This is a standard file format for map data.

Install the integration

  1. Log in to Autohive and go to Your user profile > Integrations, or Your workspace -> Integrations.

  2. Find the OpenRouteService Integration card and click Connect to workspace.

    List of integrations in Autohive

  3. Add your API key. This integration uses a free OpenRouteService key:

  4. Confirm installation. You’ll see “Connected” status.

Use the integration

Turn on OpenRouteService capabilities in Agent settings → Add capabilities. A capability is one action your agent can take.

  1. Follow our Create your first agent guide to build an agent.
  2. Turn on the capabilities you want your agent to use.
  3. Start prompting your agent with the task you want to do with OpenRouteService.

Available capabilities

Geocoding

  • Geocode Address — Find the best matching address or place.
    • Uses HeiGIT Pelias to search.
    • Defaults the country to New Zealand.
    • Flags matches below 0.8 confidence with is_low_confidence, so a person can confirm them before use.

Isochrones

  • Get Isochrone — Create drive-time areas around one point.
    • Takes one origin point and one to ten time bands.
    • Each band is 1 to 60 minutes.
    • Returns the unaltered OpenRouteService GeoJSON FeatureCollection.
    • Supports the driving-car travel profile only.
    • Every successful call also returns a bands summary with no coordinates.
    • Set export_geojson to true to also get the result as a platform file.
    • Set include_geojson to false to skip the inline GeoJSON. You then get only the file and the bands summary.
    • include_geojson set to false needs export_geojson set to true.

Travel-Time Matrix

  • Get Travel-Time Matrix — Return driving times for every labelled origin and destination pair.
    • Each point is {id, latitude, longitude} with an ID you choose.
    • Distances in metres are optional.
    • Limit: 10,000 origins, 10,000 destinations, and 10,000 pairs per request.
    • Larger matrices are split into batches and put back together, so each pair appears once.
    • Unreachable pairs return null, not 0.
    • Set export_format to json to also get a compact file.

Key features

New Zealand-first geocoding with confidence flags

Geocoding defaults its country boundary to NZ. This suits the integration’s main use case, New Zealand catchment analysis. You can still supply any ISO 3166-1 alpha-2 country code.

Matches below 0.8 confidence are flagged with is_low_confidence. A workflow can then confirm the result before it uses it in an isochrone or matrix call.

Multi-band isochrones in one request

Get Isochrone accepts up to 10 driving-time bands (for example 10, 15, and 30 minutes) in one call. It returns them all in one GeoJSON FeatureCollection, so you do not need one request per band.

Isochrones as files

Exact drive-time shapes can be very large. If they come back inline, they fill up your agent’s context. To avoid this, set export_geojson to true and include_geojson to false. Your agent gets a file it can hand to the next action or script. It also gets a short bands summary it can read directly.

Each item in bands has:

  • time_minutes for the band
  • geometry_type, polygon_count, and vertex_count for the shape
  • area_sq_km, the approximate area in square kilometres with holes taken out
  • bbox, the bounding box as [west, south, east, north]

If the file export fails, the action keeps the inline GeoJSON and adds a message. Shape data is never dropped.

If you set include_geojson to false without export_geojson, the action returns an invalid_request error for include_geojson. It does not call OpenRouteService.

Labelled travel-time matrices at scale

Get Travel-Time Matrix returns a table of driving times for every requested pair. The table lists each origin in turn, then each destination. Requests above OpenRouteService’s per-call route limit are batched and put back together for you.

The result is an origin-destination table only. It does not pick facilities or apply demographic or catchment rules.

Provider errors returned as data, not exceptions

Provider failures (rate limits, quota errors, invalid requests) come back as a normal result with result: false. A calling skill can read error_type and retry_after_seconds and decide whether to retry. Credentials and provider error bodies are never returned.

Rate limits and quotas

HeiGIT enforces two quotas per API key:

  • Per minute: a sliding 60-second limit. It returns error_type: "rate_limit". Retry after retry_after_seconds.
  • Per day: a rolling 24-hour quota. It returns error_type: "quota_exceeded" or "quota_or_unauthorized". Do not retry right away. Check the HeiGIT dashboard.

Common use cases

Demographic catchment analysis

  1. Use Geocode Address on a site or store. Confirm the match if is_low_confidence is true.
  2. Use Get Isochrone with the drive-time bands you need, such as 10, 15, and 30 minutes. Ask for a file only.
  3. Pass the file into the next step, such as a Stats NZ Datafinder query for the same area.

Delivery and service area planning

  1. Use Geocode Address on each depot or service location.
  2. Use Get Isochrone to draw the area each one can cover by drive time.
  3. Compare the areas across bands to plan service tiers.

Site selection and accessibility

  1. Use Geocode Address on each candidate site.
  2. Use Get Isochrone to see how far customers or staff can travel to each site in a set time.
  3. Compare access across the candidate sites.

Multi-site travel-time comparisons

  1. Use Geocode Address on each staff, customer, or facility location.
  2. Use Get Travel-Time Matrix with those points as labelled origins and destinations. You get driving times for every pair in one request.
  3. Compare travel time across facilities, plan rosters, or rank sites by total travel time.

Notes

  • New Zealand default, global capable: geocoding defaults to the NZ country boundary but accepts any ISO 3166-1 alpha-2 country code.
  • Driving only currently: Get Isochrone and Get Travel-Time Matrix currently support the driving-car travel profile only.
  • Isochrone limits: driving-time bands are capped at 60 minutes and 10 intervals per request. This matches OpenRouteService’s public isochrone limit.
  • Isochrone files: file export is optional. Inline GeoJSON stays the default, so existing workflows keep working.
  • Travel-time matrix limits: each of origins and destinations is capped at 10,000 points. The product (origins x destinations) is capped at 10,000 pairs per request.
  • No key leakage: the API key is passed only in the Authorization header and is never included in request URLs or action output.
  • 90-second timeout, no retry: Get Isochrone and Get Travel-Time Matrix use a 90-second timeout per request or batch. They do not retry on timeout, so a slow compute that already counted against the daily quota is not charged again.

Disconnect the integration

Important: Disconnecting removes access to OpenRouteService from your Autohive workspace.

  1. Go to Your user profile -> Connections, or Your workspace -> Integrations.
  2. Find the OpenRouteService Integration.
  3. Click Disconnect and confirm.

Data Impact: Disconnecting stops access with your stored key. It does not change any data held by OpenRouteService or your account.

About OpenRouteService

OpenRouteService is an open-source map service. It uses OpenStreetMap data and is run by HeiGIT, the Heidelberg Institute for Geoinformation Technology. It offers geocoding, routing (finding the best road route), and drive-time areas. Teams use it for logistics, access planning, and demographic analysis.