How to Find Restaurants, Fuel Stations, or Parking Along a Route

Find places along a route

You have a route and want to add a stop, such as a restaurant, fuel station, or parking place.

In this guide, you will:

1. Get the route geometry with the Routing API.
2. Find nearby places with the Places API.
3. Compare their estimated detours with the Route Matrix API.
4. Add the selected place as a new waypoint and update the route.

Example: Find restaurants within 1,000 meters of a route near Roseburg, Oregon.

Important: The search buffer measures geographic proximity, not driving time. A nearby place can still require a long detour.

1. Get the route geometry

Request details=polyline6 to add precision-6 encoded geometry. Routing waypoints use latitude,longitude, separated by |. GeoJSON response coordinates use [longitude, latitude]. These examples explicitly select drive, balanced, free_flow, and metric so the later Matrix requests use the same settings.

GET https://api.geoapify.com/v1/routing?waypoints=43.424923,-123.298537|43.120223,-123.398972&mode=drive&type=balanced&traffic=free_flow&units=metric&details=polyline6&apiKey=YOUR_API_KEY

Read features[0].properties.polyline6 for the complete route. Individual legs also contain their own polylines. The encoded string supplements the normal route geometry, so keep the returned GeoJSON for displaying the route.

2. Find places along the route

Send the encoded route geometry from the previous step to the Places API. The buffer defines how far from the route to search.

ROUTE_POLYLINE6 is a substitution marker, not a usable geometry. Your implementation must replace it with features[0].properties.polyline6 from the Routing API response.

POST https://api.geoapify.com/v2/places?apiKey=YOUR_API_KEY
Content-Type: application/json

{
  "categories": ["catering.restaurant"],
  "filter": {
    "type": "polyline",
    "geometry": "ROUTE_POLYLINE6",
    "encoding": "polyline6",
    "buffer": 1000
  },
  "limit": 20,
  "offset": 0
}

Use service.vehicle.fuel for fuel stations or parking for parking, or include multiple categories. Match encoding to the Routing API response: use polyline6 for a polyline6 string and polyline5 for a polyline5 string.

The buffer is measured in meters, must be greater than zero, and cannot exceed 100,000. When omitted, it defaults to 1,000 meters. A response contains up to limit places; use offset to request additional pages.

3. Compare estimated detours (optional)

This step is optional. Use the Route Matrix API when you want to rank candidate places by how much travel time they may add.

Calculate the added travel time

For a route from A to B and a candidate place P, calculate the detour with:

extra seconds = time(A → P) + time(P → B) − time(A → B)
extra minutes = extra seconds / 60

Matrix time values are in seconds. Time spent at the place is not included. For example, add 15 × 60 = 900 seconds separately for a 15-minute stop.

Request the required times

Use two Route Matrix requests for N candidate places:

1. Request travel times from A to every candidate: sources = [A], targets = [P1, …, PN].
2. Request travel times from every candidate to B: sources = [P1, …, PN], targets = [B].

Use features[0].properties.time from the original Routing API response for the A → B baseline. The two Matrix requests require 2N cells. Each regular Matrix request supports up to 1,000 cells. A shortlist of 20 candidates requires 40 cells in total.

Send both requests to POST https://api.geoapify.com/v1/routematrix with Content-Type: application/json and API-key authentication.

Request 1: A to each candidate

The candidate coordinates below illustrate the request structure; they are not claimed Places API results.

{
  "mode": "drive",
  "type": "balanced",
  "traffic": "free_flow",
  "units": "metric",
  "sources": [{"location": [-123.298537, 43.424923]}],
  "targets": [
    {"location": [-123.350676, 43.261954]},
    {"location": [-123.3417, 43.2165]}
  ]
}

Request 2: each candidate to B

{
  "mode": "drive",
  "type": "balanced",
  "traffic": "free_flow",
  "units": "metric",
  "sources": [
    {"location": [-123.350676, 43.261954]},
    {"location": [-123.3417, 43.2165]}
  ],
  "targets": [{"location": [-123.398972, 43.120223]}]
}

Read the matrix responses

Keep candidates in the same order in both requests.

Exclude a candidate when either Matrix travel time is missing or null. Do not calculate detours when the original route time is unavailable.

Keep estimates comparable

• Use the same mode, route type, traffic model, units, max_speed, and avoidance rules in the Routing and Matrix requests.
• Matrix results represent independent route legs and are most comparable to intermediate_waypoint_mode=stopover.
• Keep negative estimates. Snapping and routing preferences can occasionally produce a shorter route through a candidate; confirm the result with the Routing API.

Confirm the selected stop

After selecting a place, request the final A → P → B route with intermediate_waypoint_mode=stopover. Compare its properties.time with the original route time, and use the returned geometry for directions.

For a route that already has intermediate stops, evaluate the new place between each allowed pair of adjacent waypoints while preserving the required stop order.

Quick script with an AI coding agent

Copy this prompt into Codex, Claude Code, Cursor, or another coding agent to create a standalone route stop finder.

Create a standalone tool that finds useful stops along a route.

Before you start
- Ask for my preferred language and runtime.
- Ask whether the tool should run as a CLI, server process, or browser tool.
- Ask for the output format, place categories, route buffer, and whether I want detour ranking.
- Ask me to make a Geoapify API key available through GEOAPIFY_API_KEY before running live requests. Do not ask me to paste it into source code, and never print or log it.
- If I have no implementation preference, choose the simplest suitable approach and state your assumptions.

API flow
1. Accept origin and destination coordinates.
2. Call the Geoapify Routing API with details=polyline6.
3. Pass the returned route-level polyline6 to the Geoapify Places API POST endpoint with the matching encoding.
4. If detour ranking is enabled, use the original Geoapify Routing API response time for A to B. Request A to each candidate and each candidate to B with the Geoapify Route Matrix API.

Requirements
- Preserve each API's documented coordinate order.
- Bound pagination and candidate counts.
- Handle empty results, null Geoapify Route Matrix API travel times, timeouts, HTTP errors, and limited 429 retries.
- Provide concise setup and run instructions with the completed tool.

Review the generated code against the three canonical request sections in this guide. Check coordinate order, encoded-polyline precision, buffer units, Matrix indexes, API-key handling, result limits, and the final route through the selected waypoint.

Add to my project with an AI coding agent

Copy this prompt into Codex, Claude Code, Cursor, or another coding agent to add route stop discovery to an existing application.

Add a “find a stop along this route” workflow to the existing application using the Geoapify Routing API, Geoapify Places API, and optional Geoapify Route Matrix API.

Inspect first
- Determine the project's language, runtime, framework, HTTP client, map library, state management, environment configuration, tests, and deployment model.
- Reuse those choices and make the smallest necessary changes.
- Check whether a Geoapify API key is already configured. If it is missing, ask me to add one through the project's existing environment or secret-management system. Do not hardcode, print, or log it.

Clarify only what the project cannot answer
- Whether detour ranking is required.
- Where the new waypoint belongs in a multi-stop route.
- Whether browser requests use a restricted API key or a backend proxy.

Implement
1. Reuse the current Geoapify Routing API response when possible. Request details=polyline6 only when encoded geometry is missing.
2. Search with the Geoapify Places API using the matching polyline encoding, selected categories, and an explicit buffer.
3. Let the user select a place and add it as a stopover.
4. For detour ranking, use the original route time with bounded A-to-candidate and candidate-to-B Geoapify Route Matrix API requests.

Quality requirements
- Preserve loading, empty, partial, unreachable, selected, and error states.
- Cancel stale requests.
- Add focused tests.
- Report the changed files and any assumptions.

Review the generated code against the three canonical request sections in this guide. Check coordinate order, encoded-polyline precision, buffer units, Matrix indexes, API-key handling, result limits, and the final route through the selected waypoint.

Reusable UI component with an AI coding agent

Copy this prompt into Codex, Claude Code, Cursor, or another coding agent to create a reusable route stop finder component.

Create a reusable “Find a stop along the route” component using the Geoapify Routing API, Geoapify Places API, and optional Geoapify Route Matrix API.

Inspect first
- Follow the application's existing framework, component, styling, state-management, HTTP, map, accessibility, testing, and deployment conventions.
- Check whether a Geoapify API key is already configured. If it is missing, ask me to configure one through the project's environment or secret-management system.
- For browser requests, ask whether to use an origin-restricted API key or a backend proxy.
- Never hardcode, print, or log the API key.

Clarify only unresolved choices
- Supported place categories.
- Route-buffer range.
- Waypoint insertion behavior.
- Whether detour estimates are needed.

Component behavior
1. Accept the current Geoapify Routing API response and route endpoints as inputs.
2. Offer restaurant, fuel-station, and parking categories with a route-buffer control.
3. Query the Geoapify Places API with the route-level encoded polyline.
4. Show candidates in an accessible list and as map markers.
5. Clearly distinguish geographic proximity from added driving time.

Quality requirements
- Support loading, empty, partial, unreachable, selected, and error states.
- Cancel stale work and clean up resources.
- Add focused interaction and data-mapping tests.

Review the generated code against the three canonical request sections in this guide. Check coordinate order, encoded-polyline precision, buffer units, Matrix indexes, API-key handling, result limits, and the final route through the selected waypoint.

Complete route stop finder with an AI coding agent

Copy this prompt into Codex, Claude Code, Cursor, or another coding agent to build a complete route stop finder page. For a ready-made waypoint input, consider @geoapify/route-waypoint-selector to collect and order route waypoints.

Build a complete route stop finder page using the Geoapify Routing API, Geoapify Places API, and Geoapify Route Matrix API.

Before you start
- For an existing project, inspect and reuse its language, framework, HTTP client, map library, styling, state, environment, tests, and deployment conventions.
- For a new project, ask for the preferred language and runtime, browser or server architecture, map technology, categories, buffer limits, and whether detour ranking is required. If I have no preference, choose a simple suitable stack and state your assumptions.
- If the application needs a waypoint input, suggest @geoapify/route-waypoint-selector (https://www.npmjs.com/package/@geoapify/route-waypoint-selector) before building a custom one. Reuse an existing waypoint input when the project already provides one.
- Check whether a Geoapify API key is available before making live requests. If it is missing, ask me to configure one through the project's environment or secret-management system.
- For browser requests, ask whether to use an origin-restricted API key or a backend proxy.
- Never hardcode, print, or log the API key.

Feature flow
1. Let the user provide origin and destination coordinates, using @geoapify/route-waypoint-selector when it fits the project.
2. Request and display a route from the Geoapify Routing API with details=polyline6.
3. Search selected categories with the Geoapify Places API within an explicit route buffer.
4. Rank a bounded candidate set using the original route time with A-to-candidate and candidate-to-B Geoapify Route Matrix API results.
5. Add the selected place as a stopover and request the confirmed route.

Experience and reliability
- Keep route and place layers distinct.
- Provide accessible, responsive controls.
- Handle pagination limits, empty and unreachable results, stale requests, timeouts, limited 429 retries, and other API errors.
- Add focused tests and provide a concise verification report.

Review the generated code against the three canonical request sections in this guide. Check coordinate order, encoded-polyline precision, buffer units, Matrix indexes, API-key handling, result limits, and the final route through the selected waypoint.

Show results and limits

Display the route and places

• Keep the route and places in separate map layers.
• Show candidates as markers and in an accessible list with their estimated extra travel time.
• After selection, request and display the route through that stop.
• Keep the original place point for the marker. Routing and Matrix may snap it to a nearby accessible road.
• Show selection with text as well as color, and insert place names with textContent.

Mark partial results

Set clear limits. For example, request up to five pages of 20 places and rank the first 20 candidates.

• Set partialSearch: true when the final allowed page is full.
• Set shortlistTruncated: true when some candidates were not ranked.
• Tell users that partial results may exclude the place with the smallest detour.

Handle empty results and errors

• Treat no places or no reachable places as valid results, and skip empty Matrix requests.
• Bound requests, apply timeouts, and retry HTTP 429 responses only a few times with backoff.
• Cancel stale searches when the route changes.
• Keep API keys in environment configuration. Use a restricted key or backend proxy for browser applications, and never expose keys in logs or errors.