DEV Community: Geoapify Maps API

Why Reverse Geocoding Doesn’t Return the Exact Clicked Location

Alfiya Tarasenko — Wed, 15 Apr 2026 00:42:58 +0000

When you click on a map and request an address for that exact point, you might expect a perfect match.

But in practice, the returned address can differ slightly from the location you clicked — sometimes by just a few meters, sometimes more.

If you’ve noticed this behavior in your app, you’re not dealing with a bug. It’s a natural result of how reverse geocoding works.

In this article, we’ll explore why the address you get doesn’t always exactly match the clicked map point, and what this means when building map-based applications.

This example uses a simple map demo powered by the Geoapify Reverse Geocoding API , so you can see this behavior in action.

👉 CodePen demo / code sample

What Reverse Geocoding Actually Returns

Reverse geocoding doesn’t return the exact point you clicked.

Instead, it returns the closest known addressable location in the dataset. That’s a key difference.

Coordinates represent a continuous space — every point on the map has a latitude and longitude.

Addresses, on the other hand, are discrete. They only exist where real-world objects are defined:

buildings
entrances
parcels
points of interest

So when you click somewhere on the map, the system has to answer a different question:

“What is the nearest meaningful address to this point?”

Not:

“What exists exactly at this coordinate?”

What this means in practice

Clicking on a road → returns a nearby building or street address
Clicking inside a park → returns the nearest street or POI
Clicking near a building → returns the building’s registered address point

Even if the difference is just a few meters, it’s expected behavior.

How Far Is the Returned Location from the Clicked Point?

Once you understand that reverse geocoding returns the nearest address, the next logical question is:

How far is the returned result from the original point?

There isn’t just one answer — because there are two different ways to measure distance.

1. Distance to the Returned Object (Geometry Distance)

When the returned result represents a building or boundary, the distance is calculated between:

your clicked point
and the geometry (polygon) of that object

This leads to an important detail:

👉 If your point is inside the building polygon, the distance can be 0,

even if the returned coordinate (for example, the entrance) is several meters away:

{
  "results": [
    {
      "country": "Germany",
      "city": "Nuremberg",
      "postcode": "90425",
      "street": "Pretzfelder Straße",
      "housenumber": "15",
      "lon": 11.064715,
      "lat": 49.4718661,
      "result_type": "building",
      "formatted": "Pretzfelder Straße 15, 90425 Nuremberg, Germany",
      "distance": 0
    }
  ],
  "query": {
    "lat": 49.47177742331178,
    "lon": 11.064803253993091
  }
}

Example:

You click inside a large building
The address is tied to the entrance
The API may report distance = 0 (because you are inside the building)
But visually, the returned point is offset

2. Real Distance Between Coordinates

This is the actual distance between:

the clicked point
and the returned coordinate

This is what you usually need if you want to measure the visible offset.

Option 1: Haversine Formula

You can calculate the distance between two coordinates using the Haversine formula:

d = 2r * arcsin(√(sin²((lat2 - lat1) / 2) + cos(lat1) * cos(lat2) * sin²((lon2 - lon1) / 2)))

Where:

lat1, lon1 = clicked point
lat2, lon2 = returned location
r = Earth radius (≈ 6371 km)

Option 2: Using Turf.js

If you're working in JavaScript, you can use a geospatial library like Turf.js to calculate distances easily.

@turf/distance handles geographic calculations for you and returns accurate results in different units, so you don’t need to implement the formula manually.

import distance from '@turf/distance';

const from = [lon1, lat1];
const to = [lon2, lat2];

const dist = distance(from, to, { units: 'meters' });

Option 3: Using Geoapify Geometry API

You can also calculate distances using the Geoapify Geometry Operations API.

This API lets you calculate distances between geometries — including points, lines, and polygons — without implementing the logic yourself.

Example request:

POST https://api.geoapify.com/v1/geometry/operation?apiKey=YOUR_API_KEY

{
  "operation": "distance",
  "point1": {"type": "Point", "coordinates": [lon1, lat1]},
  "point2": {"type": "Point", "coordinates": [lon2, lat2]},
  "params": {
    "units": "kilometers"
  }
}

This approach is useful when you want:

server-side calculations
consistent results across services
support for complex geometries (not just points)

It can also be integrated into AI agents or automated workflows, where distance calculations are part of a larger decision-making process (for example, validating locations or triggering actions based on proximity).

Code Sample: Try It on a Map

Seeing this in action makes the behavior much easier to understand.

Try clicking on different locations in this interactive demo:

👉 CodePen demo / code sample

What to test:

Click directly on a building
Click on a road
Click inside a park or open area
Click near building edges or entrances

You’ll notice that:

the returned address doesn’t always match the exact clicked point
the marker may appear slightly shifted
results depend on nearby addressable objects

This makes it easier to see how reverse geocoding behaves in real-world scenarios.

How to Handle This in Your App

To avoid confusion when working with reverse geocoding:

Don’t expect exact matches — results are approximate
Show both clicked and returned locations if needed
Use distance thresholds for validation
Prefer geometry checks (e.g., inside building) for higher accuracy
Communicate clearly that the address is the nearest one

These small adjustments can significantly improve user experience.

Is There a Free UK Postcode Lookup API?

Alfiya Tarasenko — Sat, 11 Apr 2026 21:42:33 +0000

At first glance, the answer seems like yes. There are several APIs that let you search postcodes and return location or address data — for example, the Geoapify Postcode API.

But if you try a few of them, you’ll notice something: results can differ. Some APIs return more complete data, others return partial results — or nothing at all for the same postcode.

Even well-known providers can be inconsistent. The reason isn’t the API. It’s the data.

In the UK, the most complete postcode and address dataset is owned by Royal Mail and distributed under license. Free alternatives exist, but they are never fully complete or fully up to date.

What is a postcode in the UK?

UK postcodes are part of the addressing system used by Royal Mail.

In practice, postcodes are linked to specific geographic points where real addresses are grouped. Each postcode represents a set of properties assigned to that location.

Unlike unique identifiers, a single postcode usually corresponds to multiple addresses — sometimes just a few buildings, sometimes dozens.

Example of postcode locations in London. Each point represents a postcode linked to a group of addresses. Source: ONS Postcode Directory (Live)

Postcodes were designed for mail delivery, not precise mapping. That’s why they are often represented as points (centroids) rather than exact building locations.

⚠️ Even when postcode locations are available, it’s not always clear which postcode a specific building belongs to. A postcode represents a group of addresses, not a single precise location.

Who owns UK postcode data?

The most complete postcode and address dataset in the UK is maintained by Royal Mail as part of the Postcode Address File (PAF). It contains the full mapping between postcodes and individual addresses.

However, it is not open data.

Access to Royal Mail data is licensed, which means it cannot be freely used, shared, or redistributed. Most developers don’t access it directly, but through official distributors and resellers such as Ideal Postcodes, Postcoder, or Loqate.

This creates several practical challenges:

Higher cost compared to open alternatives
Licensing restrictions (storage, caching, redistribution)
Limited flexibility for building public or large-scale services

As a result, this data is often unavailable to developers who need free, open, or permissively licensed solutions — forcing them to rely on alternative datasets.

Are there free UK postcode lookup solutions?

Yes — there are several free and open solutions available. However, they differ in coverage, structure, and use cases.

Open data sources

Here are the main open datasets used for UK postcode lookup:

Name	Link	Description
ONS Postcode Directory (ONSPD)	Dataset link	The most complete open dataset. Provides postcode coordinates and administrative areas, but no full addresses.
GeoNames	Dataset link	Global dataset with partial UK postcode coverage. Simpler and less detailed.
OpenStreetMap	Website	Crowdsourced dataset where postcodes are often assigned directly to buildings or areas. Coverage and accuracy vary.

These datasets are free and open, but they do not provide full postcode → address mapping.

Postcode lookup APIs based on open data

To make these datasets easier to use, you can rely on APIs built on top of open data.

One example is the Geoapify Postcode API.

It allows you to:

Search by postcode
Get coordinates and address information
Use a simple HTTP API

Geoapify combines multiple open data sources (such as OpenStreetMap and GeoNames) to provide practical postcode lookup functionality.

Here’s a request example:

curl "https://api.geoapify.com/v1/postcode/search?postcode=TW2%207LS&countrycode=gb&geometry=original&apiKey=YOUR_API_KEY"

And response example:

{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "properties": {
        "postcode": "TW2 7LS",
        "lon": -0.3583,
        "lat": 51.4513,
        "datasource": {
          "sourcename": "geonames",
          "attribution": "GeoNames",
          "license": "CC BY 4.0",
          "url": "https://www.geonames.org/datasources/"
        },
        "country": "United Kingdom",
        "country_code": "gb",
        "state": "England",
        "city": "Greater London",
        "district": "London Borough of Richmond upon Thames",
        "formatted": "London, TW2 7LS, United Kingdom"
      },
      "geometry": {
        "type": "Point",
        "coordinates": [-0.3583, 51.4513]
      }
    }
  ]
}

⚠️ Results are based on open data sources and may differ from official Royal Mail data.

Free vs Official UK Postcode Data: Which One to Use?

The right choice depends on your use case and requirements.

Comparison

	Proprietary data (Royal Mail PAF)	Open data solutions
Coverage	Most complete	High but incomplete
Addresses	Full address list	Limited or none
Accuracy	Highest	Good, but varies
Cost	Paid	Free
Licensing	Restricted	Open / permissive
Best for	Validation, delivery, checkout	Maps, search, analytics

When to use proprietary data

Use Royal Mail-based solutions (via licensed providers) if you need:

Accurate address validation
Checkout or form autofill
Delivery and logistics systems
Guaranteed coverage

When to use open solutions

Use open data and APIs (like Geoapify) if you need:

Postcode → location lookup
Mapping and visualization
General search functionality
Free or open-source-friendly solutions

Conclusion

So, is there a free UK postcode lookup API?

Yes — but with limitations.

Free and open solutions can work well for many use cases, especially for mapping, search, and general applications. But they rely on datasets that are not fully complete.

If you need accurate, address-level data, you’ll need access to Royal Mail’s licensed dataset.

In the end, UK postcode accuracy is not a technical problem — it’s a data ownership problem.

If you want to try a free solution yourself, explore the Geoapify Postcode API Playground and test postcode lookup in practice.

Google Places API Alternatives: Which POI API Should You Use in 2026?

Alfiya Tarasenko — Wed, 08 Apr 2026 12:37:13 +0000

If your app needs to search for places — cafes, restaurants, shops, or any other points of interest — chances are you’ve looked at the Google Maps Platform first.

It’s a powerful solution, but it’s not always the best fit. Pricing, usage limits, licensing restrictions, or simply the need for more flexibility often push developers to look for alternatives.

What we’ll explore

In this article, we’ll take a practical look at Places APIs — focusing on one common use case:

Finding places by category. For example: cafes or restaurants near a location

We’ll compare how place search works across several popular providers and when each one makes the most sense to use:

Google Maps Platform — Places API
Geoapify — Places API
Foursquare — Places API
HERE Technologies — Geocoding & Search API
TomTom — Search API (POI search)
What to choose?

Use Case: Find Restaurants in Miami Beach

To keep this comparison practical, let’s use one specific scenario:

Find restaurants near this point in Miami Beach:

Latitude: 25.777415
Longitude: -80.132432

This is a good test case because every provider in this article supports location-based place search, but they expose it in different ways.

Key differences to keep in mind

Request structure: Some APIs use simple query parameters (location, radius, category), while others require more structured requests or additional configuration.
Search capabilities: APIs vary in how they support filtering, ranking, and biasing results.
Data sources: Some providers rely on proprietary datasets, while others are based on open data sources like OpenStreetMap.
Result format: The structure and level of detail in responses can differ significantly.

Even for a simple task like finding nearby restaurants, the choice of API can lead to very different results and developer experience.

Google Maps Platform — Places API

📘 Docs · 🔎 Playground · 💰 Pricing · ⚖️ Terms

The Google Maps Platform Places API is one of the most widely used solutions for working with points of interest.

It provides rich and detailed place data — including ratings, reviews, opening hours, and more — and is often the default choice for developers building location-based features.

Example request

POST https://places.googleapis.com/v1/places:searchNearby
Content-Type: application/json
X-Goog-Api-Key: YOUR_API_KEY
X-Goog-FieldMask: places.displayName,places.location,places.rating,places.reviews,places.photos

{
  "includedPrimaryTypes": ["restaurant"],
  "maxResultCount": 10,
  "locationRestriction": {
    "circle": {
      "center": {
        "latitude": 25.777415,
        "longitude": -80.132432
      },
      "radius": 1000
    }
  }
}

This request searches for restaurants near the given coordinates in Miami Beach within a 1 km radius and returns a limited set of fields.

Example response

{
  "places": [
    {
      "id": "sample-place-id-001",
      "displayName": {
        "text": "Sample Restaurant"
      },
      "formattedAddress": "100 Example St, Miami Beach, FL 33139, USA",
      "location": {
        "latitude": 25.778102,
        "longitude": -80.131245
      },
      "rating": 4.4,
      "userRatingCount": 1842,
      "websiteUri": "https://www.example.com",
      "nationalPhoneNumber": "(305) 555-0142",
      "regularOpeningHours": {
        "openNow": true,
        "weekdayDescriptions": [
          "Monday: 11:00 AM – 10:00 PM"
        ]
      },
      "primaryType": "restaurant",
      "primaryTypeDisplayName": {
        "text": "Restaurant"
      }
    }
  ]
}

The response can include much more than basic place information. In addition to name, location, and rating, the API can return reviews, photos, contact details, opening hours, and various attributes describing the place.

Reviews are returned directly in the response, while photos are provided as references that can be used to request actual images via a separate endpoint.

The exact data you receive depends on the fields specified in the X-Goog-FieldMask.

Pros

Rich place data — includes ratings, reviews, photos, opening hours, and many additional attributes
Flexible field selection — control response size and content via X-Goog-FieldMask
Large dataset — backed by a widely used platform with high user contribution and coverage

Cons

Pricing can scale quickly — depends on number of requests and fields requested, so cost estimation is important
Strict licensing terms — usage is limited by Google Maps Platform Terms, including requirements on how data is displayed, where it can be used, and integration with Google services
Data usage limitations — place data often cannot be stored long-term or used outside Google services
More complex requests — requires POST requests and field masks instead of simple query parameters

Geoapify — Places API

📘 Docs · 🔎 Playground · 💰 Pricing · ⚖️ Terms

Geoapify Places API provides access to POI data based on open data sources such as OpenStreetMap.

It focuses on simplicity and flexibility, offering a straightforward way to search for places by category, location, and additional filters.

Example request

GET https://api.geoapify.com/v2/places?categories=catering.restaurant&filter=circle:-80.132432,25.777415,1000&limit=10&apiKey=YOUR_API_KEY

This request searches for restaurants near the given coordinates in Miami Beach within a 1 km radius.

The API uses a simple GET request with query parameters, making it easy to test and integrate.

Example response

{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "properties": {
        "name": "Bella Cuba",
        "formatted": "Bella Cuba, 1659 Washington Avenue, Miami Beach, FL 33139, United States of America",
        "lat": 25.7909549,
        "lon": -80.1316981,
        "categories": [
          "catering",
          "catering.restaurant",
          "catering.restaurant.cuban"
        ],
        "catering": {
          "cuisine": "cuban"
        },
        "distance": 265,
        "datasource": {
          "sourcename": "openstreetmap",
          "license": "Open Database License",
          "attribution": "© OpenStreetMap contributors"
        },
        "raw": {
            "osm_id": 3057276069,
            "osm_type": "n"
          }
      },
      "geometry": {
        "type": "Point",
        "coordinates": [-80.1316981, 25.7909549]
      }
    }
  ]
}

The response uses a standard GeoJSON-like structure, which is especially convenient for map applications. Depending on available source data, results may include categories, cuisine, phone number, website, opening hours, and other attributes.

The datasource field is especially useful because it makes the data origin explicit. In this example, the results come from OpenStreetMap, with attribution and license information included in the response.

The raw.osm_id and raw.osm_type values allow you to link back to the original OpenStreetMap object — for example: view this place in OpenStreetMap >>

Pros

Open data (OpenStreetMap-based) — transparent data source that allows you to cache, store, and redistribute data, depending on the OpenStreetMap license terms
Affordable pricing model — as a service provider (not a data owner), Geoapify offers more cost-efficient and predictable pricing
Simple and intuitive API — uses GET requests with clear query parameters, making it easy to test and integrate
Flexible usage — not tightly coupled to a specific platform, allowing more freedom in how data is stored and displayed
GeoJSON-like response format — ready to use directly in mapping libraries without transformation

Cons

No built-in reviews or ratings — unlike Google, the API does not provide user-generated reviews, ratings, or photos
Data completeness varies — coverage and quality depend on OpenStreetMap data in the region
Less enriched data — fewer high-level attributes compared to Google’s dataset
May require additional data sources — some features (e.g. reviews or popularity) may require integration with other APIs

Foursquare — Places API

📘 Docs · 💰 Pricing · ⚖️ Terms

Foursquare Places API provides access to a global POI dataset enriched with location intelligence and user behavior signals.

It is known for its structured place data and strong categorization system, making it well-suited for search and discovery use cases.

curl --request GET \
     --url 'https://api.foursquare.com/v3/places/search?ll=25.777415%2C-80.132432&radius=1000&categories=restaurants' \
     --header 'X-Places-Api-Version: 2023-10-01' \
     --header 'accept: application/json'

This request searches for restaurants near the given coordinates in Miami Beach within a 1 km radius.

Foursquare uses category IDs instead of text-based categories, which allows precise filtering but requires referencing their category taxonomy.

Example response

{
  "results": [
    {
      "fsq_id": "5f8a9c1b2d_example",
      "name": "Ocean Breeze Grill",
      "location": {
        "formatted_address": "200 Ocean Dr, Miami Beach, FL 33139",
        "locality": "Miami Beach",
        "region": "FL",
        "country": "US"
      },
      "geocodes": {
        "main": {
          "latitude": 25.778245,
          "longitude": -80.130912
        }
      },
      "categories": [
        {
          "id": 13065,
          "name": "Restaurant",
          "short_name": "Restaurant"
        }
      ],
      "distance": 180,
      "rating": 4.3,
      "price": 2,
      "tel": "+1 305-555-0199",
      "website": "https://oceanbreeze.example.com",

      "hours": {
        "display": "Mon–Sun 11:00 AM – 11:00 PM",
        "open_now": true
      },

      "features": {
        "services": {
          "delivery": true,
          "takeout": true,
          "dine_in": {
            "reservations": true
          }
        },
        "food_and_drink": {
          "meals": {
            "lunch": true,
            "dinner": true
          },
          "alcohol": {
            "beer": true,
            "wine": true
          }
        },
        "amenities": {
          "outdoor_seating": true,
          "wifi": "free"
        }
      },

      "photos": [
        {
          "id": "photo_001",
          "prefix": "https://fastly.4sqi.net/img/general/",
          "suffix": "/12345_sample.jpg",
          "width": 800,
          "height": 600
        }
      ],

      "tips": [
        {
          "id": "tip_001",
          "text": "Great seafood and ocean views. Try the grilled snapper!",
          "agree_count": 12
        }
      ],

      "stats": {
        "total_ratings": 540,
        "total_photos": 120,
        "total_tips": 34
      },

      "popularity": 0.82,
      "verified": true
    }
  ],
  "context": {
    "geo_bounds": {
      "circle": {
        "center": {
          "latitude": 25.777415,
          "longitude": -80.132432
        },
        "radius": 1000
      }
    }
  }
}

The response includes core place information such as name, location, categories, and distance. Depending on the endpoint and plan, Foursquare can also provide additional enrichment such as ratings, popularity signals, and place attributes.

Pros

Rich and structured place data — includes categories, attributes, popularity signals, and user-generated content
Includes user-generated content — provides photos and tips, adding useful context to places, though the coverage and depth may vary compared to larger platforms like Google Maps Platform
Strong categorization system — enables precise filtering using a well-defined taxonomy (category IDs)
High-quality curated dataset — especially strong in urban areas and commercial locations
Enriched data signals — provides popularity, trends, and behavioral insights beyond basic POI data

Cons

Strict licensing restrictions — data is provided under a limited, revocable license and must be used only within your application; you cannot store, merge, redistribute, or build your own POI dataset, and must display “Powered by Foursquare” attribution
Limited external usage — reports or demos must be non-monetized, non-competitive, and cannot expose material portions of data
Category-based filtering complexity — requires working with category IDs instead of simple text queries
Pricing scales with usage — costs can increase with request volume and data enrichment

HERE Technologies — Places API

📘 Docs · 🔎 Playground · 💰 Pricing · ⚖️ Terms

HERE Technologies provides location services and POI data through its Discover endpoint, which allows searching for places by category, location, and filters.

It is widely used in navigation, mobility, and enterprise applications, especially where accurate geolocation is critical.

Example request

GET https://discover.search.hereapi.com/v1/discover?at=25.777415,-80.132432&q=restaurant&limit=10&apiKey=YOUR_API_KEY

This request searches for restaurants near the given coordinates in Miami Beach.

Example response

{
  "items": [
    {
      "id": "here-poi-001",
      "title": "Ocean Breeze Restaurant",
      "resultType": "place",

      "address": {
        "label": "150 Ocean Dr, Miami Beach, FL 33139, United States",
        "countryCode": "USA",
        "countryName": "United States",
        "stateCode": "FL",
        "state": "Florida",
        "city": "Miami Beach",
        "street": "Ocean Dr",
        "postalCode": "33139",
        "houseNumber": "150"
      },

      "position": {
        "lat": 25.778215,
        "lng": -80.131102
      },

      "distance": 210,

      "categories": [
        {
          "id": "100-1000-0000",
          "name": "Restaurant",
          "primary": true
        }
      ],

      "foodTypes": [
        {
          "id": "101-000",
          "name": "Seafood",
          "primary": true
        }
      ],

      "contacts": [
        {
          "phone": [
            {
              "value": "+1 305-555-0188"
            }
          ],
          "www": [
            {
              "value": "https://oceanbreeze.example.com"
            }
          ]
        }
      ],

      "openingHours": [
        {
          "text": [
            "Mon–Sun: 11:00 AM – 11:00 PM"
          ],
          "isOpen": true
        }
      ],

      "timeZone": {
        "name": "America/New_York",
        "utcOffset": "-04:00"
      },

      "chains": [
        {
          "id": "chain-001",
          "name": "Ocean Breeze Group"
        }
      ],

      "media": {
        "images": {
          "items": [
            {
              "href": "https://images.example.com/photo1.jpg",
              "supplier": {
                "id": "tripadvisor"
              }
            }
          ]
        },
        "ratings": {
          "items": [
            {
              "count": 320,
              "average": 4.2,
              "supplier": {
                "id": "tripadvisor"
              }
            }
          ]
        }
      }
    }
  ],
  "count": 1,
  "limit": 10,
  "offset": 0
}

The HERE API returns structured place data with a strong focus on address details, categories, and consistency across regions.

Depending on the available data, the response may include:

Contact details such as phone numbers and websites
Opening hours in both structured and human-readable formats
Categories and food types for classification
Media and ratings, often sourced from third-party providers (for example, TripAdvisor)
Extended attributes such as EV charging stations, fuel information, or logistics-related data

Compared to consumer-focused APIs, HERE emphasizes reliable, standardized data and global coverage rather than building its own user-generated content ecosystem.

Pros

Reliable global coverage — strong presence across multiple regions and industries, including automotive and logistics
Structured and consistent data — predictable response format with detailed address components and classification
Simple request model — supports text-based and location-based search without complex request bodies
Enterprise-focused features — includes extended attributes such as EV stations, fuel data, and logistics-related information
Third-party enrichment — may include ratings and media from external providers (for example, TripAdvisor)

Cons

Proprietary dataset — data is not open and cannot be freely stored, reused, or redistributed
Limited user-generated content — generally does not provide native reviews or rich photo ecosystems like larger consumer platforms
Licensing restrictions — usage is governed by HERE terms, including limitations on storage, redistribution, and usage scope
Pricing scales with usage — costs depend on request volume and service usage

TomTom — Places API

📘 Docs · 🔎 Playground · 💰 Pricing · ⚖️ Terms

TomTom provides access to place data through its Search and Places APIs, allowing developers to search for POIs by category, name, or geographic location.

It is widely used in navigation, mobility, and enterprise applications, with a focus on accurate geolocation and global coverage.

Example request

curl -X GET "https://api.tomtom.com/search/2/categorySearch/restaurants.json?lat=25.777415&lon=-80.132432&radius=1000&categorySet=7315&view=Unified&relatedPois=off&key=YOUR_API_KEY" \
  -H "accept: */*"

This request searches for restaurants within a 1 km radius around Miami Beach and returns categorized place results using TomTom’s Places API.

Example response

{
  "summary": {
    "query": "restaurants",
    "queryType": "NON_NEAR",
    "numResults": 10,
    "offset": 0,
    "totalResults": 84,
    "geoBias": {
      "lat": 25.777415,
      "lon": -80.132432
    }
  },
  "results": [
    {
      "type": "POI",
      "id": "tomtom-poi-001",
      "score": 2.57,
      "dist": 145.3,
      "poi": {
        "name": "Ocean Breeze Cafe",
        "phone": "+1 305-555-0181",
        "url": "www.oceanbreeze.example.com",
        "categorySet": [
          {
            "id": 7315
          }
        ],
        "categories": [
          "restaurant"
        ],
        "classifications": [
          {
            "code": "RESTAURANT",
            "names": [
              {
                "nameLocale": "en-US",
                "name": "restaurant"
              }
            ]
          }
        ]
      },
      "address": {
        "streetNumber": "120",
        "streetName": "Ocean Dr",
        "municipality": "Miami Beach",
        "countrySubdivision": "FL",
        "postalCode": "33139",
        "countryCode": "US",
        "country": "United States",
        "freeformAddress": "120 Ocean Dr, Miami Beach, FL 33139"
      },
      "position": {
        "lat": 25.778201,
        "lon": -80.131502
      },
      "entryPoints": [
        {
          "type": "main",
          "position": {
            "lat": 25.77812,
            "lon": -80.13144
          }
        }
      ]
    },
    {
      "type": "POI",
      "id": "tomtom-poi-002",
      "score": 2.56,
      "dist": 210.8,
      "poi": {
        "name": "Seaside Grill",
        "categorySet": [
          {
            "id": 7315
          }
        ],
        "categories": [
          "restaurant"
        ]
      },
      "address": {
        "freeformAddress": "200 Collins Ave, Miami Beach, FL 33139"
      },
      "position": {
        "lat": 25.77901,
        "lon": -80.13088
      }
    }
  ]
}

The response includes a summary section plus a list of matching POIs. For each result, TomTom returns core place information such as the place name, categories, address, coordinates, and distance. Some results may also include contact details like a phone number or website.

A useful detail is the entryPoints field, which can help in routing and navigation scenarios by showing where the place can actually be accessed.

Pros

Reliable global location data — strong coverage optimized for navigation and mobility use cases
Well integrated with routing services — works seamlessly with routing, traffic, and navigation APIs
Simple and developer-friendly API — clear parameters and predictable responses
Accurate positioning data — includes fields like entryPoints for real-world navigation

Cons

Limited focus on user-generated content — minimal support for reviews or community-driven insights
Limited media support — photos and rich media are not part of standard responses
Proprietary dataset — data cannot be freely stored or redistributed
Licensing restrictions — usage is constrained by TomTom terms and conditions

What to choose?

Choosing a Places API depends not only on features, but also on your use case, constraints, and budget. Here’s a practical way to approach it.

1. Define your goal

Start with what you actually need to build:

Rich place details (reviews, photos, popularity signals) → Best fit: Google Maps Platform, Foursquare, HERE
Category-based search with structured place data (no need for reviews) → Best fit: Geoapify, TomTom, HERE
Navigation, routing, fleet, or logistics applications

→ Best fit: TomTom, HERE, Geoapify

👉 If your app relies on user-generated content, your main options are Google or Foursquare.

2. Consider your budget early

Pricing models differ significantly:

Google Maps Platform → powerful but can scale in cost quickly
Foursquare → commercial dataset with flexible plans
HERE / TomTom → enterprise-oriented pricing, often bundled with other services
Geoapify → affordable and predictable pricing

👉 Always estimate usage before building — especially for high-traffic apps.

3. Check licensing and data restrictions

This is often a deciding factor:

Some providers restrict storing or caching data (e.g., Google)
Some allow more flexibility with usage and storage
Most require attribution

👉 If you need to store or reuse data, this can narrow your options quickly.

4. Match provider strengths

Each provider is optimized for different scenarios:

Google / Foursquare → rich place content and discovery
HERE / TomTom → navigation, routing, and enterprise mobility
Geoapify → flexible APIs with open-data foundation, providing access to OpenStreetMap (OSM) data

👉 Example:

Building a city discovery app → Foursquare or Geoapify
Building a delivery platform → HERE or TomTom
Building an infrastructure or utility app (electricity, supply, field services) → Geoapify, TomTom, or HERE

5. Think long-term

Switching providers later can be costly.

Consider:

scaling costs
API limits
vendor lock-in
data portability

Summary

There is no single “best” API — only the best fit for your case.

Choose Google or Foursquare for rich place content
Choose HERE or TomTom for routing and mobility
Choose Geoapify for flexibility, open data, and cost efficiency

👉 The right choice comes down to balancing features, budget, and licensing constraints.

How to Get City, Postal Code, Address from Latitude and Longitude

Alfiya Tarasenko — Tue, 31 Mar 2026 11:45:23 +0000

In many applications, you don’t start with an address — you start with coordinates.

A user clicks on a map, shares their GPS location, or your system receives latitude and longitude from a device. But raw coordinates like 40.748817, -73.985428 aren’t very useful on their own. Most applications need human-readable data: a city name, a postal code, or a full address.

This is where reverse geocoding comes in.

In this article, we’ll look at how to convert latitude and longitude into structured address data — including city, postal code, and formatted address — and, more importantly, what developers should be aware of when working with real-world location data.

To make things more practical, we’ll also use a simple interactive demo where you can click on a map and instantly get the corresponding address details:

CodePen Live Demo

Coordinates vs Address: Two Ways to Describe a Location

Latitude and longitude coordinates describe an exact point on Earth using a global grid system.

latitude defines how far north or south a location is
longitude defines how far east or west it is

Together, they pinpoint a precise location anywhere on the planet:

For example, the coordinates 40.748817, -73.985428 represent a specific point in New York.

However, while coordinates are extremely precise, they are not very intuitive for humans. People naturally think of locations in terms of:

cities
streets
postal codes
full addresses

This creates a gap between how machines represent locations and how humans understand them.

So how do you convert coordinates into a readable address?

To do that, you need a process that maps latitude and longitude to real-world location data — such as city names and postal codes. This process is called reverse geocoding.

Reverse Geocoding: Convert Coordinates to City, Postal Code, and Address

Reverse geocoding is the process of converting geographic coordinates (latitude and longitude) into a human-readable address.

In practice, reverse geocoding is not something you implement locally. It requires access to large, constantly updated geographic datasets that map coordinates to real-world address data — including administrative boundaries, streets, buildings, and postal codes.

Because of this, reverse geocoding is typically provided as a service via APIs.

One example is the Geoapify Reverse Geocoding API, which allows you to send coordinates and receive structured address data in response.

Here is an example API Request:

https://api.geoapify.com/v1/geocode/reverse?lat=40.748817&lon=-73.985428&format=json&apiKey=YOUR_API_KEY

The response contains structured fields such as:

city, town, village
postcode
street, housenumber
formatted (full address)

You can also control the level of detail using the type parameter, which helps filter results by address level (for example: city, postcode, street, etc.).

Getting city from coordinates

To get the city from coordinates, you can use reverse geocoding with the type=city parameter. This tells the API to return results at the city level.

For example:

https://api.geoapify.com/v1/geocode/reverse?lat=40.719726903683636&lon=-74.04103305850015&format=json&type=city&apiKey=YOUR_API_KEY

A typical response looks like this:

{
  "results": [
    {
      "country": "United States",
      "state": "New Jersey",
      "city": "Jersey City",
      "lon": -74.047455,
      "lat": 40.7215682,
      "result_type": "city",
      "formatted": "Jersey City, NJ, United States of America",
      "address_line1": "Jersey City, NJ",
      "address_line2": "United States of America",
      ...
    }
  ]
}

Using type=city ensures that the response focuses on the city-level administrative area, rather than returning street-level or building-level details.

Getting postcode (ZIP code) from coordinates

To get the postal code from coordinates, you can use reverse geocoding with the type=postcode parameter. This ensures the API returns results at the postcode level.

For example:

https://api.geoapify.com/v1/geocode/reverse?lat=40.739501996228256&lon=-74.18542863164123&type=postcode&format=json&apiKey=YOUR_API_KEY

A typical response looks like this:

{
  "results": [
    {
      "country": "United States",
      "state": "New Jersey",
      "city": "Newark",
      "postcode": "07103",
      "result_type": "postcode",
      "formatted": "Newark, NJ 07103, United States of America",
      "address_line1": "Newark, NJ 07103",
      "address_line2": "United States of America"
    }
  ]
}

The key field here is:

postcode — contains the postal (ZIP) code for the given coordinates

Additional useful fields include:

city — the associated city
formatted — full human-readable address

Using type=postcode ensures that the response focuses specifically on postcode-level data.

Keep in mind that:

not all locations have postal codes
postal codes may represent areas rather than exact points
formats vary depending on the country

Getting address from coordinates

To get a full address from coordinates, you can use reverse geocoding without specifying a type, which returns the most relevant place for the given location (for example, a building, POI, or street address).

For example:

https://api.geoapify.com/v1/geocode/reverse?lat=40.68818115914695&lon=-73.99558678565592&format=json&apiKey=YOUR_API_KEY

A typical response looks like this:

{
  "results": [
    {
      "name": "Citi Bike - Congress St & Clinton St",
      "housenumber": "183",
      "street": "Congress Street",
      "city": "New York",
      "postcode": "11201",
      "state": "New York",
      "country": "United States",
      "result_type": "amenity",
      "formatted": "Citi Bike - Congress St & Clinton St, 183 Congress Street, New York, NY 11201, United States of America",
      "address_line1": "Citi Bike - Congress St & Clinton St",
      "address_line2": "183 Congress Street, New York, NY 11201, United States of America"
    }
  ]
}

The most useful field for display is:

formatted — a ready-to-use human-readable address

You can also access individual components such as:

name — place or POI name (if available)
housenumber and street
city, postcode, state, country

By default, reverse geocoding returns the most relevant result for the given coordinates, which may be a specific place (like a business or landmark), not just a street or city.

Common Pitfalls When Converting Coordinates to Address

Reverse geocoding is powerful, but working with real-world location data comes with a few important caveats.

Understanding these will help you avoid common mistakes and build more reliable applications.

City is not always available

Not every location has a city field. Depending on where the coordinates point, the response may include:

city
town
village
or no settlement at all

To handle this correctly, always implement a fallback strategy instead of relying on a single field.

The result depends on the exact point

Small changes in coordinates can lead to different results.

For example, clicking on:

a building → returns a specific address
a road → returns street-level data
a park → may return only city or district

This is expected behavior, not an error.

The closest result may not match expectations

Reverse geocoding returns the nearest known object.

This could be:

a building
a business (POI)
a street
an administrative area

If you need a specific level (e.g., city or postcode), use the type parameter to control the result.

Coordinates may need normalization

Coordinates should always be valid:

latitude must be between -90 and 90
longitude must be between -180 and 180

Try It Yourself: Interactive Reverse Geocoding Demo

To better understand how reverse geocoding works in practice, try this interactive demo:

Live Demo on CodePen

The demo also shows how different clicks can return different types of results depending on the location — for example, a building, a street, or an administrative area.

Summary

Converting latitude and longitude into a city, postal code, or full address is a common requirement in many applications — from delivery services to map-based interfaces.

In this article, we explored how reverse geocoding works and how to use it to extract meaningful location data from coordinates.

Key takeaways:

coordinates describe precise locations, but are not human-friendly
reverse geocoding bridges the gap between coordinates and real-world addresses
you can extract specific data like city and postcode using the type parameter
not all locations have complete address data, so fallback logic is important
results may vary depending on the exact coordinates and context

By understanding these concepts and handling edge cases properly, you can build reliable features that convert coordinates into usable address information.

Additional Resources

FAQ

Is reverse geocoding free?

Most reverse geocoding services offer a free tier with usage limits.

For example, Geoapify provides a free plan with 3000 requests per day and 5RPS. This is usually enough for testing and small applications. For production use or higher volumes, paid plans are available.

How do I get an API key?

To use a reverse geocoding service like Geoapify, you need an API key.

You can get one by registering at the website.

After creating a project, you’ll receive an API key that you can use in your requests.

How do I get the timezone from coordinates?

Reverse geocoding responses often include timezone information.

For example, Geoapify returns a timezone object with:

{
  "name": "America/New_York",
  "offset_STD": "-05:00",
  "offset_STD_seconds": -18000,
  "offset_DST": "-04:00",
  "offset_DST_seconds": -14400,
  "abbreviation_STD": "EST",
  "abbreviation_DST": "EDT"
}

You can extract this directly from the response without making a separate API call.

How do I get the state or region?

To get the state or region from coordinates, you can use reverse geocoding with the type=state parameter. This ensures the API returns results at the state level.

How can I understand the quality of the result?

You can estimate how accurate the result is using the distance field.

distance represents how far (in meters) the returned result is from the input coordinates
smaller values indicate higher accuracy

For example:

0–10 meters → very precise (building-level)
10–100 meters → good accuracy
100+ meters → approximate result

Why do I sometimes get a place (POI) instead of an address?

By default, reverse geocoding returns the most relevant nearby object.

This could be:

a business or landmark (POI)
a building
a street
an administrative area

If you need a specific level (e.g., city or postcode), use the type parameter to control the result.

Can I use reverse geocoding offline?

In most cases, no.

Reverse geocoding requires large and frequently updated datasets, making it impractical to run locally. That’s why it is typically provided as an online API service.

What happens if there are no results?

In some cases, reverse geocoding may return no results:

remote areas
oceans or lakes
incomplete data coverage

Your application should handle this gracefully and provide fallback behavior.

How to Visualize Multiple Overlapping Routes on a MapLibre GL Map

Casey Rivers — Fri, 27 Mar 2026 11:21:10 +0000

When building route planners, logistics dashboards, or public transport maps, you often need to display multiple routes that share the same roads. Without proper handling, these routes stack on top of each other and only the last-drawn route is visible. Users cannot compare routes or even confirm that all paths are displayed.

In a previous tutorial, we explored three approaches to solve this problem in Leaflet. MapLibre GL offers a simpler solution: the built-in line-offset paint property. No plugins, no geometry manipulation - just a single property that visually shifts each route by a specified number of pixels.

This tutorial shows how to use line-offset to display multiple overlapping routes clearly on a MapLibre GL map.

Try the live demo:
View on CodePen

APIs used:

Routing API - calculate routes between waypoints
Map Tiles API - vector map style
Map Marker Icon API - custom markers

What you will learn:

When overlapping routes are a problem and how to solve it
How to use MapLibre GL's line-offset property
Understanding the line layer paint parameters
Creating custom markers with the Map Marker Icon API

When Overlapping Routes Matter
The Solution: line-offset Property
Set Up Routes and Offsets
Add Route Layers with Offset
Understanding the Paint Parameters
Add Custom Markers
Explore the Demo
Summary
FAQ

When Overlapping Routes Matter

Multiple routes sharing the same roads is common in several scenarios:

Route Planners
When comparing alternative routes from A to B, the paths often overlap near the origin and destination. Users need to see all options to make informed decisions about travel time, distance, or toll roads.

Delivery and Logistics
Multiple drivers heading to the same warehouse or distribution center converge on the same streets. Dispatchers need to see all routes simultaneously to coordinate timing and identify bottlenecks.

Public Transport Maps
Bus or train lines frequently share corridors. A transit map that only shows one line per street fails to communicate the actual service coverage.

Multi-stop Route Comparison
When planning trips with multiple waypoints, users might want to compare different orderings. The routes will share many segments but differ in key sections.

In all these cases, stacked routes create confusion. The map appears to show fewer routes than expected, and users cannot visually compare the paths.

Four routes from different Paris landmarks to the Arc de Triomphe. Each route is visible even where they share the same streets.

The Solution: line-offset Property

MapLibre GL provides a built-in solution: the line-offset paint property. This property shifts the rendered line perpendicular to its direction by a specified number of pixels.

paint: {
    "line-color": "#E53935",
    "line-width": 4,
    "line-offset": -6  // Shift 6 pixels to the left
}

Key characteristics of line-offset:

Pixel-based: The offset is in screen pixels, not meters. Routes maintain consistent visual separation at all zoom levels.
Perpendicular shift: The line moves sideways relative to its direction, creating parallel paths.
No geometry modification: The underlying coordinates remain unchanged. Only the visual rendering is affected.
Positive/negative values: Positive values shift right (relative to line direction), negative values shift left.

For four routes, we use offsets like [-6, -2, 2, 6] to spread them evenly across a 12-pixel width.

This is much simpler than the Leaflet approaches we covered previously. In Leaflet, you need external libraries like Turf.js for geometric offset or plugins like leaflet-polylineoffset. MapLibre GL handles it natively.

Set Up Routes and Offsets

Define your routes with different colors and assign pixel offsets to each:

const DESTINATION = {
    lat: 48.8738,
    lon: 2.2950,
    name: "Arc de Triomphe"
};

const ROUTES = [
    {id: "r1", name: "From Eiffel Tower", color: "#E53935", origin: {lat: 48.8584, lon: 2.2945}},
    {id: "r2", name: "From Louvre", color: "#43A047", origin: {lat: 48.8606, lon: 2.3376}},
    {id: "r3", name: "From Notre-Dame", color: "#1E88E5", origin: {lat: 48.8530, lon: 2.3499}},
    {id: "r4", name: "From Sacré-Cœur", color: "#FB8C00", origin: {lat: 48.8867, lon: 2.3431}}
];

// Offset in pixels for parallel routes (visual offset only)
const OFFSETS = [-6, -2, 2, 6];

The offset values spread routes symmetrically: two routes shift left (-6, -2 pixels) and two shift right (2, 6 pixels). This keeps the routes centered on the actual road.

API Key: Sign up at geoapify.com to get your API key.

Add Route Layers with Offset

Each route needs two layers: an outline (darker, wider) and the main line (route color, narrower). The outline creates visual depth and helps routes stand out from the map.

function addRouteLayer(routeId) {
    const route = routeState[routeId];
    const offsetPixels = OFFSETS[route.index % OFFSETS.length];

    // Add source with original route geometry (no geometric offsetting)
    map.addSource(routeId, {
        type: "geojson",
        data: route.feature
    });

    // Add outline layer with pixel-based visual offset
    map.addLayer({
        id: `${routeId}-outline`,
        type: "line",
        source: routeId,
        layout: {
            "line-join": "round",
            "line-cap": "round"
        },
        paint: {
            "line-color": darkenColor(route.color, 30),
            "line-width": 7,
            "line-opacity": 0.9,
            "line-offset": offsetPixels
        }
    });

    // Add main line layer with same pixel-based visual offset
    map.addLayer({
        id: `${routeId}-line`,
        type: "line",
        source: routeId,
        layout: {
            "line-join": "round",
            "line-cap": "round"
        },
        paint: {
            "line-color": route.color,
            "line-width": 4,
            "line-opacity": 1,
            "line-offset": offsetPixels
        }
    });
}

Both layers use the same line-offset value so the outline and main line move together. The outline is 7 pixels wide, the main line is 4 pixels, creating a 1.5-pixel border on each side.

Understanding the Paint Parameters

The line layer paint properties control how routes appear on the map. Here's what each parameter does:

line-offset

"line-offset": offsetPixels  // e.g., -6, -2, 2, or 6

The core parameter for this tutorial. It shifts the line perpendicular to its direction:

Negative values shift the line to the left (relative to the line direction)
Positive values shift the line to the right
Zero draws the line on the actual coordinates

For multiple routes, distribute offsets evenly. With 4 routes using [-6, -2, 2, 6], routes are spaced 4 pixels apart, creating a total width of 12 pixels.

line-width

"line-width": 7  // outline
"line-width": 4  // main line

The thickness of the line in pixels. The outline is wider than the main line to create a border effect. The difference (7 - 4 = 3 pixels) is split between both sides, giving a 1.5-pixel border.

line-color

"line-color": darkenColor(route.color, 30)  // outline - 30% darker
"line-color": route.color                    // main line - original color

The outline uses a darkened version of the route color. This creates depth and helps distinguish overlapping routes. The darkenColor helper reduces RGB values by a percentage.

line-opacity

"line-opacity": 0.9  // outline - slightly transparent
"line-opacity": 1    // main line - fully opaque

Opacity ranges from 0 (invisible) to 1 (fully opaque). The outline is slightly transparent (0.9) to soften the border effect.

Layout properties: line-join and line-cap

layout: {
    "line-join": "round",
    "line-cap": "round"
}

line-join: How line segments connect at corners. "round" creates smooth curves at turns. Other options: "miter" (sharp corners), "bevel" (flat corners).
line-cap: How line ends are drawn. "round" adds a semicircle at each end. Other options: "butt" (flat end), "square" (flat end extended by half the line width).

Using "round" for both creates smooth, professional-looking routes.

The line-offset property shifts each route perpendicular to its direction, creating clear visual separation.

Add Custom Markers

Use the Geoapify Map Marker Icon API to create markers for origins and the destination. Each origin marker matches its route color, making it easy to identify which path starts where.

function createMarker(lon, lat, color, iconName, name, label) {
    const el = document.createElement("div");
    el.style.width = "36px";
    el.style.height = "48px";
    el.style.backgroundImage = `url(https://api.geoapify.com/v2/icon?type=awesome&color=${color}&icon=${iconName}&iconType=awesome&size=48&scaleFactor=2&apiKey=${API_KEY})`;
    el.style.backgroundSize = "contain";
    el.style.backgroundRepeat = "no-repeat";
    el.style.cursor = "pointer";

    const popup = new maplibregl.Popup({offset: [0, -48]})
        .setHTML(`<strong>${name}</strong><br>${label}`);

    const marker = new maplibregl.Marker({element: el, anchor: "bottom"})
        .setLngLat([lon, lat])
        .setPopup(popup)
        .addTo(map);

    return marker;
}

Map Marker Icon API Parameters

The marker URL includes several parameters to customize the icon. See the full Marker Icon API documentation for all options.

Parameter	Value	Description
`type`	`awesome`	Marker style. Options: `material` (Material Design shape), `awesome` (Font Awesome marker shape), `circle`, `plain` (no background)
`color`	`%23E53935`	Background color of the marker in hex (URL-encoded `#` as `%23`)
`icon`	`flag`, `circle`	Name of the inner icon. Depending on `iconType`, use Material Design icon names or Font Awesome v6 icon names
`iconType`	`awesome`	Icon library: `material` or `awesome`. Default depends on marker type
`size`	`48`	Icon image height in pixels
`scaleFactor`	`2`	Multiplier for retina displays (2x resolution)

The destination uses a flag icon, while origins use circle icons with colors matching their routes.

MapLibre GL Marker Options

new maplibregl.Marker({element: el, anchor: "bottom"})

element: Custom HTML element to use as the marker (instead of default pin)
anchor: Which part of the element sits on the coordinates. "bottom" places the pin tip on the location

The popup offset [0, -48] positions it above the marker (negative Y moves up).

Explore the Demo

The interactive demo shows four routes from Paris landmarks to the Arc de Triomphe. You can:

Toggle routes using checkboxes to show/hide individual paths
Click a route in the list to zoom and see details
Compare visually how routes overlap and diverge

Notice how the line-offset property keeps all routes visible even on shared road segments. Each color remains distinct without any complex geometry manipulation.

Summary

MapLibre GL's line-offset property provides a simple, built-in solution for displaying multiple overlapping routes. Unlike Leaflet, which requires external libraries or plugins, MapLibre GL handles parallel route visualization natively.

Key points:

line-offset is pixel-based - Routes maintain consistent visual separation at all zoom levels
No geometry modification - The underlying coordinates stay unchanged; only rendering is affected
Simple implementation - Just add "line-offset": pixelValue to your paint properties
Works with outlines - Apply the same offset to both outline and main line layers

Recommended offset values:

For 2-3 routes: [-4, 0, 4] or [-3, 3]
For 4 routes: [-6, -2, 2, 6]
For more routes: Spread evenly, keeping total width under 20 pixels

When to use this approach:

Comparing alternative routes between the same points
Displaying multiple delivery or logistics routes
Building public transport maps with shared corridors
Any scenario where users need to see all routes simultaneously

Useful links:

FAQ

Q: How does line-offset compare to Turf.js lineOffset?
A: MapLibre GL's line-offset is a visual/pixel-based offset applied during rendering. Turf.js lineOffset modifies the actual geometry in meters. The MapLibre approach is simpler and maintains consistent screen-space separation at all zoom levels. Turf.js creates truly parallel paths in geographic space, which may be better for precise geographic analysis.

Q: What happens at sharp turns or intersections?
A: The line-offset property handles corners reasonably well due to the line-join: round setting. At very sharp turns, you might see slight visual artifacts, but for typical road networks this is rarely noticeable.

Q: Can I change the offset dynamically?
A: Yes. Use map.setPaintProperty(layerId, 'line-offset', newValue) to update the offset without removing and re-adding layers. This is useful for interactive applications where users might adjust the separation.

Q: How many routes can I display before performance suffers?
A: MapLibre GL uses GPU rendering and handles dozens of routes efficiently. The line-offset calculation is done on the GPU, so it adds minimal overhead. For hundreds of routes, consider server-side simplification or clustering.

Q: Can I use different offsets at different zoom levels?
A: Yes. MapLibre GL expressions support zoom-based interpolation. For example:

"line-offset": [
    "interpolate", ["linear"], ["zoom"],
    10, 2,  // 2 pixels at zoom 10
    16, 8   // 8 pixels at zoom 16
]

Q: What marker icon types are available?
A: The Map Marker Icon API supports four types: material (Material Design shape), awesome (Font Awesome marker shape), circle (simple circle), and plain (no background shape). Each can include an icon from Font Awesome v6 or Material Design Icons libraries.

Try It Now

Open the Live Demo

How to Visualize and Style Routes on a MapLibre GL Map

Casey Rivers — Mon, 16 Mar 2026 09:26:59 +0000

In a previous tutorial, we covered route visualization with Leaflet. Now let's explore how to achieve the same with MapLibre GL.

MapLibre GL offers powerful styling capabilities through its expression-based paint properties. Unlike raster-based libraries, MapLibre GL renders everything with WebGL, which means smooth zooming, rotation, and crisp lines at any scale.

The key difference from Leaflet: MapLibre GL uses layers and sources instead of direct GeoJSON rendering. This approach offers more flexibility - you can update styles without re-adding layers, and the GPU handles rendering efficiently.

This tutorial shows how to build a route visualization with interactive styling controls using MapLibre GL. You will learn to work with GeoJSON sources, line layers, and the Map Marker Icon API for custom markers.

APIs used:

Routing API - calculate route between waypoints
Map Tiles API - vector map style
Map Marker Icon API - custom waypoint markers

What you will learn:

How to add GeoJSON sources and line layers in MapLibre GL
Creating route outlines with layer ordering
Using setPaintProperty for dynamic style updates
Building custom markers with HTML elements
Differences from Leaflet route visualization

Why MapLibre GL for Routes
Set Up the Map
Add Route Layers
Update Styles Dynamically
Create Custom Markers
Build Interactive Controls
MapLibre GL vs Leaflet: Key Differences
Explore the Demo
Summary
FAQ

Why MapLibre GL for Routes

MapLibre GL brings several advantages for route visualization:

Vector rendering: Lines stay crisp at any zoom level
GPU acceleration: Smooth performance even with complex routes
Dynamic styling: Update colors and widths without re-rendering
Built-in line offset: Native support for parallel route lines (useful for multi-route displays)
3D capabilities: Pitch and bearing for immersive views

The trade-off is a steeper learning curve. MapLibre GL uses a declarative approach where you define sources (data) and layers (how to render data) separately.

Set Up the Map

MapLibre GL loads a complete style JSON instead of individual tile layers:

const map = new maplibregl.Map({
    container: "map",
    style: `https://maps.geoapify.com/v1/styles/osm-bright/style.json?apiKey=${API_KEY}`,
    center: [2.3376, 48.8606], // Paris [lng, lat]
    zoom: 13
});

map.addControl(new maplibregl.NavigationControl(), "bottom-right");

Note the coordinate order: MapLibre GL uses [longitude, latitude] (GeoJSON standard), while Leaflet uses [latitude, longitude].

Key: Sign up at geoapify.com to get your API key.

Add Route Layers

In MapLibre GL, add a GeoJSON source first, then create layers that reference it:

map.addSource("route", {
    type: "geojson",
    data: routeData
});

// Outline layer (rendered first, appears below)
map.addLayer({
    id: "route-outline",
    type: "line",
    source: "route",
    layout: { "line-join": "round", "line-cap": "round" },
    paint: {
        "line-color": outlineColor,
        "line-width": routeWidth + outlineWidth * 2,
        "line-opacity": routeOpacity
    }
});

// Main route layer
map.addLayer({
    id: "route-line",
    type: "line",
    source: "route",
    layout: { "line-join": "round", "line-cap": "round" },
    paint: {
        "line-color": routeColor,
        "line-width": routeWidth,
        "line-opacity": routeOpacity
    }
});

By adding the outline layer first, MapLibre GL draws it below the main route. The outline width is routeWidth + outlineWidth * 2 so outlineWidth pixels show on each side.

Here's how the route looks with and without outline:

Update Styles Dynamically

MapLibre GL's setPaintProperty method changes styles instantly without re-adding layers:

map.setPaintProperty("route-line", "line-color", routeColor);
map.setPaintProperty("route-line", "line-width", routeWidth);
map.setPaintProperty("route-line", "line-opacity", routeOpacity);

map.setPaintProperty("route-outline", "line-color", outlineColor);
map.setPaintProperty("route-outline", "line-width", showOutline ? routeWidth + outlineWidth * 2 : 0);

This is more efficient than Leaflet's approach. The GPU updates rendering without recreating geometry.

Create Custom Markers

MapLibre GL markers use HTML elements. Create a div with the marker image as background:

const el = document.createElement("div");
el.style.width = `${dimensions.width}px`;
el.style.height = `${dimensions.height}px`;
el.style.backgroundImage = `url(${iconUrl})`;
el.style.backgroundSize = "contain";

const marker = new maplibregl.Marker({element: el, anchor: dimensions.anchor})
    .setLngLat([wp.lon, wp.lat])
    .setPopup(popup)
    .addTo(map);

The anchor property determines which part of the element sits on the coordinates:

"center": Element center on coordinates (good for circles)
"bottom": Bottom center on coordinates (good for pins)

Build Interactive Controls

Controls call updateRouteStyle() instead of re-rendering layers:

document.getElementById("route-color").addEventListener("input", (e) => {
    document.getElementById("route-color-value").textContent = e.target.value.toUpperCase();
    updateRouteStyle();
});

document.getElementById("marker-type").addEventListener("change", renderMarkers);

The pattern: listen for input changes, update the displayed value, and call the appropriate update function.

MapLibre GL vs Leaflet: Key Differences

Aspect	Leaflet	MapLibre GL
Coordinate order	[lat, lng]	[lng, lat]
Adding routes	`L.geoJSON(data).addTo(map)`	Source + Layer
Style updates	Remove and re-add layer	`setPaintProperty()`
Layer ordering	Custom panes	Layer add order
Markers	`L.icon()` with image URL	HTML elements
Line offset	Plugin required	Built-in `line-offset`
Performance	Good for simple routes	Better for complex routes

When to use MapLibre GL:

Complex routes with many points
Need for 3D views (pitch/bearing)
Multiple overlapping routes (built-in line offset)
Frequent style updates
Vector tile base maps

When to use Leaflet:

Simpler learning curve
Existing Leaflet codebase
Raster tile base maps
Extensive plugin ecosystem

Explore the Demo

The interactive demo lets you experiment with all styling parameters in real-time. Try adjusting:

Route styling - color, width, and opacity
Outline effects - toggle, color, and width
Marker types - awesome pins, material pins, or circles
Marker size - from 32px to 80px
Shadow toggle - for markers

MapLibre GL's setPaintProperty() makes these updates instant without re-rendering the entire route. Play with different combinations to see how MapLibre GL handles dynamic styling.

👉 Try the live demo:

Summary

MapLibre GL provides powerful tools for route visualization with excellent performance and flexible styling. This tutorial covered:

Sources and layers: The MapLibre GL approach to data and rendering
Layer ordering: Outline below route by adding layers in order
Dynamic updates: Using setPaintProperty() for efficient style changes
HTML markers: Creating custom markers with the Map Marker Icon API
Coordinate order: Remember [lng, lat] for MapLibre GL

Recommended settings:

Route width: 5-8 pixels
Outline width: 1-3 pixels (appears on each side)
Opacity: 0.8-1.0 for clear visibility
Marker size: 40-56 pixels

Key takeaways:

MapLibre GL uses sources (data) and layers (rendering) separately
setPaintProperty() updates styles without re-rendering
Layer order determines z-index (first added = bottom)
HTML markers offer full customization flexibility
Built-in line offset makes multi-route visualization easier

Useful links:

FAQ

Q: What's the main advantage of MapLibre GL over Leaflet for routes?

A: Dynamic style updates without re-rendering. With MapLibre GL, you can change colors, widths, and other properties instantly using setPaintProperty(). Leaflet requires removing and re-adding layers. This makes MapLibre GL better for interactive styling or real-time updates.

Q: Why does MapLibre GL use [lng, lat] instead of [lat, lng]?

A: MapLibre GL follows the GeoJSON specification, which uses [longitude, latitude] order. This is the international standard. Leaflet uses [lat, lng] for historical reasons and to match common geographic notation.

Q: Can I use raster tiles with MapLibre GL?

A: Yes, but it's not the primary use case. MapLibre GL is optimized for vector tiles. If you need raster tiles, Leaflet is often simpler. However, MapLibre GL can load raster sources if needed.

Q: How do I handle route clicks in MapLibre GL?

A: Use map.on('click', 'layer-id', function(e) { ... }) where 'layer-id' is your route layer ID. MapLibre GL's event system is layer-based rather than object-based like Leaflet.

Q: What's the performance difference for complex routes?

A: MapLibre GL uses GPU rendering, which handles complex geometries better than Leaflet's canvas/SVG approach. For routes with thousands of coordinate points or multiple routes, MapLibre GL typically performs better, especially at higher zoom levels.

Q: Can I animate routes with MapLibre GL?

A: Yes. You can animate by updating the source data progressively or using the line-dasharray property with animation. MapLibre GL's GPU rendering makes animations smoother than Leaflet for complex routes.

Q: How do I show multiple routes with different colors?

A: Add each route as a separate feature in the GeoJSON source, then use data-driven styling with expressions in the paint properties. For example: 'line-color': ['get', 'color'] where each feature has a 'color' property.

Try It Now

👉 Open the Live Demo

How to Visualize Multiple Overlapping Routes on a Leaflet Map

Casey Rivers — Tue, 10 Mar 2026 10:43:06 +0000

When you display multiple routes on a map, they often share the same roads. Without proper handling, routes stack directly on top of each other and become impossible to distinguish. Users see a confusing mess of colors instead of clear, separate paths.

This is a common problem in logistics dashboards, delivery tracking apps, and any scenario where you compare routes from different origins to a common destination. The challenge is making each route visually distinct while keeping the map readable.

In this tutorial, we explore three practical approaches to solve this problem using Leaflet:

Turf.js lineOffset - Geometric offset that creates truly parallel routes
Varying line weights - Visual layering without any offset
leaflet-polylineoffset plugin - Pixel-based visual offset

Each technique has its strengths. We will walk through the implementation of the first two (the simplest and most effective), compare all three, and help you decide which fits your project.

Try the live demos:

APIs used:

Routing API - calculate routes between waypoints
Map Tiles API - base map layer
Map Marker Icon API - custom markers

What you will learn:

How to fetch multiple routes from the Routing API
Three techniques for separating overlapping route lines
When to use geometric offset vs visual layering vs pixel offset
Adding custom markers for origins and destinations

The Problem: Overlapping Routes
Set Up the Map and Fetch Routes
Approach 1: Geometric Offset with Turf.js
Approach 2: Varying Line Weights
Approach 3: Pixel Offset with leaflet-polylineoffset
Add Custom Markers
Visual Comparison at Different Zoom Levels
Comparison: Which Approach to Use
Explore the Demos
Summary
FAQ

The Problem: Overlapping Routes

Imagine a delivery service with multiple drivers heading to the same warehouse. Each driver starts from a different location, but as they approach the destination, their routes converge onto the same streets. On a map, this creates a visual problem: the routes overlap completely, and only the last-drawn route is visible.

This happens because:

Routes share common road segments near the destination
Leaflet draws polylines directly on top of each other
Only the topmost line color shows through

The result? Users cannot see all routes at once. They might think routes are missing, or they cannot compare travel times visually.

We need a way to separate these overlapping lines so each route remains visible and identifiable.

Set Up the Map and Fetch Routes

All three approaches share the same foundation: a Leaflet map with routes fetched from the Geoapify Routing API.

Include required libraries

<link rel="stylesheet" href="https://unpkg.com/leaflet@1.9.4/dist/leaflet.css">
<script src="https://unpkg.com/leaflet@1.9.4/dist/leaflet.js"></script>

For the Turf.js approach, also include:

<script src="https://unpkg.com/@turf/turf@7/turf.min.js"></script>

Define routes and destination

We will use Paris landmarks as our example: four routes from different origins all heading to the Arc de Triomphe.

const API_KEY = "YOUR_API_KEY";

const DESTINATION = {
    lat: 48.8738,
    lon: 2.2950,
    name: "Arc de Triomphe"
};

const ROUTES = [
    {id: "r1", name: "From Eiffel Tower", color: "#E53935", origin: {lat: 48.8584, lon: 2.2945}},
    {id: "r2", name: "From Louvre", color: "#43A047", origin: {lat: 48.8606, lon: 2.3376}},
    {id: "r3", name: "From Notre-Dame", color: "#1E88E5", origin: {lat: 48.8530, lon: 2.3499}},
    {id: "r4", name: "From Sacré-Cœur", color: "#FB8C00", origin: {lat: 48.8867, lon: 2.3431}}
];

Key: Please sign up at geoapify.com and generate your own API key.

Initialize the map

const map = L.map("map", {zoomControl: false}).setView([48.866, 2.32], 13);
L.control.zoom({position: "bottomright"}).addTo(map);

L.tileLayer(`https://maps.geoapify.com/v1/tile/osm-bright/{z}/{x}/{y}@2x.png?apiKey=${API_KEY}`, {
    attribution: '© <a href="https://www.geoapify.com/">Geoapify</a> © OpenMapTiles © OpenStreetMap',
    maxZoom: 20
}).addTo(map);

Fetch routes from the Routing API

const routeState = {};

ROUTES.forEach((route, index) => {
    const waypoints = `${route.origin.lat},${route.origin.lon}|${DESTINATION.lat},${DESTINATION.lon}`;
    const url = `https://api.geoapify.com/v1/routing?waypoints=${waypoints}&mode=drive&apiKey=${API_KEY}`;

    fetch(url)
        .then(res => res.json())
        .then(data => {
            if (!data.features?.[0]) return;

            const feature = data.features[0];
            const props = feature.properties;

            routeState[route.id] = {
                ...route,
                index: index,
                visible: true,
                feature: feature,
                layer: createRouteLayer(feature, route.color, index),
                distance: (props.distance / 1000).toFixed(1),
                duration: Math.round(props.time / 60)
            };
        });
});

The Routing API returns GeoJSON features containing the route geometry. We store each route in routeState for later manipulation (toggling visibility, fitting bounds, etc.).

Approach 1: Geometric Offset with Turf.js

The first approach uses Turf.js lineOffset to create geometrically parallel routes. Instead of drawing routes on top of each other, we shift each route by a fixed distance in meters.

Define offset distances

// Geometric offset distances in meters
const OFFSET_METERS = [-15, -5, 5, 15];

These values spread the routes across a 30-meter width. Negative values shift left, positive values shift right (relative to the route direction).

Create offset route layers

function createRouteLayer(feature, color, index) {
    const group = L.layerGroup();

    // Get offset distance in meters for this route
    const offsetMeters = OFFSET_METERS[index % OFFSET_METERS.length];

    // Apply Turf.js lineOffset to create geometrically offset route
    let offsetFeature;
    try {
        offsetFeature = turf.lineOffset(feature, offsetMeters / 1000, {units: 'kilometers'});
    } catch (error) {
        console.warn('Turf.js offset failed, using original geometry:', error);
        offsetFeature = feature;
    }

    // Render each part separately (handle MultiLineString)
    const parts = extractGeoJSONParts(offsetFeature.geometry);
    for (const part of parts) {
        addCasedPolyline(group, part, color);
    }

    group.getBounds = () => L.featureGroup(group.getLayers()).getBounds();
    return group.addTo(map);
}

The key line is turf.lineOffset(feature, offsetMeters / 1000, {units: 'kilometers'}). This takes the original route geometry and returns a new geometry shifted perpendicular to the route by the specified distance.

Note: Turf.js uses kilometers as the default unit, so we divide meters by 1000.

Draw cased polylines

For better visibility, we draw each route with a darker outline (casing) behind the main line:

function addCasedPolyline(group, latLngs, color) {
    // Outline (casing)
    const outline = L.polyline(latLngs, {
        color: darkenColor(color, 30),
        weight: 7,
        opacity: 0.9,
        lineCap: "round",
        lineJoin: "bevel",
        smoothFactor: 1
    });
    outline.addTo(group);

    // Main line
    const main = L.polyline(latLngs, {
        color,
        weight: 4,
        opacity: 1,
        lineCap: "round",
        lineJoin: "bevel",
        smoothFactor: 1
    });
    main.addTo(group);
}

Helper: Extract coordinates from GeoJSON

function extractGeoJSONParts(geometry) {
    if (geometry.type === "LineString") {
        return [geometry.coordinates.map(([lon, lat]) => [lat, lon])];
    }
    if (geometry.type === "MultiLineString") {
        return geometry.coordinates.map(line => line.map(([lon, lat]) => [lat, lon]));
    }
    return [];
}

GeoJSON uses [longitude, latitude] order, but Leaflet expects [latitude, longitude]. This function handles the conversion and supports both LineString and MultiLineString geometries.

Routes are geometrically offset so each path is visible even where they share the same roads.

Approach 2: Varying Line Weights

The second approach is simpler: instead of offsetting routes, we draw them with different line thicknesses. Thicker routes are drawn first (bottom layer), thinner routes are drawn last (top layer). This creates a visual stacking effect where all colors remain visible.

Define line weights

// Line weights for each route (thickest to thinnest)
const LINE_WEIGHTS = [
    {outline: 14, main: 10},  // Route 1 - thickest (bottom layer)
    {outline: 11, main: 7},   // Route 2
    {outline: 8, main: 5},    // Route 3
    {outline: 5, main: 3}     // Route 4 - thinnest (top layer)
];

Create layered route polylines

function createRouteLayer(feature, color, index) {
    const group = L.layerGroup();

    // Get line weights for this route index
    const weights = LINE_WEIGHTS[index % LINE_WEIGHTS.length];

    // Render each part separately (handle MultiLineString)
    const parts = extractLatLngParts(feature.geometry);
    for (const part of parts) {
        addCasedPolyline(group, part, color, weights);
    }

    group.getBounds = () => L.featureGroup(group.getLayers()).getBounds();
    return group.addTo(map);
}

function addCasedPolyline(group, latLngs, color, weights) {
    // Outline (casing) - darker version of route color
    const outline = L.polyline(latLngs, {
        color: darkenColor(color, 30),
        weight: weights.outline,
        opacity: 0.9,
        lineCap: "round",
        lineJoin: "bevel",
        smoothFactor: 1
    });
    outline.addTo(group);

    // Main line - route color
    const main = L.polyline(latLngs, {
        color,
        weight: weights.main,
        opacity: 1,
        lineCap: "round",
        lineJoin: "bevel",
        smoothFactor: 1
    });
    main.addTo(group);
}

This approach requires no external library. The routes still overlap geometrically, but the varying thicknesses create a layered effect where each color peeks through.

Varying line weights create visual separation without geometric offset.

Approach 3: Pixel Offset with leaflet-polylineoffset

The third approach uses the leaflet-polylineoffset plugin to apply a visual pixel-based offset. Unlike Turf.js which modifies the geometry, this plugin shifts the rendered line on screen.

Include the plugin

<script src="https://cdn.jsdelivr.net/npm/leaflet-polylineoffset@1.1.1/leaflet.polylineoffset.min.js"></script>

Define pixel offsets

// Pixel-based offsets (visual only, not geometric)
const BASE_OFFSETS = [-4, -1.5, 1.5, 4];
const MIN_OFFSET_PX = 2.5; // Minimum visible offset

Create offset polylines with zoom handling

The actual implementation scales offsets based on zoom level and rebuilds routes when zoom changes:

// Re-render routes on zoom end
map.on("zoomend", () => {
    for (const r of Object.values(routeState)) {
        if (!r.visible) continue;
        if (r.layer) map.removeLayer(r.layer);
        r.layer = createRouteLayer(r.feature, r.color, r.index);
    }
});

function createRouteLayer(feature, color, index) {
    const group = L.layerGroup();
    const z = map.getZoom();

    // Scale offset based on zoom, but keep a minimum
    const base = BASE_OFFSETS[index % BASE_OFFSETS.length];
    const scale = z >= 18 ? 0.6 : z >= 16 ? 0.85 : 1;
    const offsetPx = Math.sign(base) * Math.max(Math.abs(base * scale), MIN_OFFSET_PX);

    const parts = extractLatLngParts(feature.geometry);
    for (const part of parts) {
        addCasedPolyline(group, part, color, offsetPx);
    }

    group.getBounds = () => L.featureGroup(group.getLayers()).getBounds();
    return group.addTo(map);
}

function addCasedPolyline(group, latLngs, color, offsetPx) {
    const outline = L.polyline(latLngs, {
        color: darkenColor(color, 30),
        weight: 7,
        opacity: 0.9,
        lineCap: "round",
        lineJoin: "bevel"
    });
    outline.setOffset?.(offsetPx);  // Plugin method
    outline.addTo(group);

    const main = L.polyline(latLngs, {
        color,
        weight: 4,
        opacity: 1,
        lineCap: "round",
        lineJoin: "bevel"
    });
    main.setOffset?.(offsetPx);  // Plugin method
    main.addTo(group);
}

The setOffset() method is added by the plugin. It shifts the rendered line by the specified number of pixels without modifying the underlying coordinates.

Note: This approach requires rebuilding routes on zoom changes to maintain consistent visual spacing, which adds complexity compared to the other approaches.

Pixel-based offset using the leaflet-polylineoffset plugin.

Add Custom Markers

All three approaches benefit from clear markers at origins and destination. We use the Geoapify Map Marker Icon API to generate custom pin icons.

function renderMarkers() {
    markers.forEach(m => map.removeLayer(m));
    markers = [];

    // Destination marker (flag icon)
    markers.push(
        createMarker(DESTINATION.lat, DESTINATION.lon, "%23E91E63", "flag", DESTINATION.name, "Destination")
    );

    // Origin markers (circle icon, matching route color)
    Object.values(routeState).forEach(route => {
        if (!route.visible) return;

        const color = route.color.replace("#", "%23");
        const name = route.name.replace("From ", "");
        markers.push(
            createMarker(route.origin.lat, route.origin.lon, color, "circle", name, "Origin")
        );
    });
}

function createMarker(lat, lon, color, iconName, name, label) {
    const iconUrl = `https://api.geoapify.com/v2/icon?type=awesome&color=${color}&icon=${iconName}&iconType=awesome&size=48&scaleFactor=2&apiKey=${API_KEY}`;

    const icon = L.icon({
        iconUrl: iconUrl,
        iconSize: [36, 48],
        iconAnchor: [18, 48],
        popupAnchor: [0, -48]
    });

    return L.marker([lat, lon], {icon})
        .bindPopup(`<strong>${name}</strong><br>${label}`)
        .addTo(map);
}

Each origin marker uses the same color as its route, making it easy to match markers to paths visually.

Visual Comparison at Different Zoom Levels

Understanding how each approach behaves at different zoom levels helps you choose the right one for your use case.

Default Zoom (City Overview - Zoom 13)

At the default zoom level, all approaches show the routes clearly:

Left: Turf.js lineOffset | Center: Varying line weights | Right: leaflet-polylineoffset

Zoomed In (Street Level - Zoom 16)

When zoomed in closer, the differences become more apparent:

At higher zoom, Turf.js shows clear geometric separation. Line weights stack visually. Pixel offset maintains consistent screen spacing.

Zoomed Out (District View - Zoom 11)

At lower zoom levels, routes converge more:

At lower zoom, all approaches look similar. However, pixel offset (right) may show routes displaced from their actual path - notice the orange route appears shifted incorrectly.

Comparison: Which Approach to Use

Aspect	Turf.js lineOffset	Varying Line Weights	leaflet-polylineoffset
Dependencies	Turf.js (~70KB)	None	Plugin (~5KB)
Code complexity	Moderate	Simple	Complex
Visual result	Truly parallel routes	Layered/stacked routes	Visually offset
Best at high zoom	Excellent	Good	Good
Best at low zoom	Good	Routes stay together	May show displacement
Zoom handling	No rebuild needed	No rebuild needed	Needs rebuild on zoom
Performance	Slightly slower	Fast	Moderate

When to use Turf.js lineOffset (Recommended)

You need routes to be visually distinct at all zoom levels
Routes are relatively short (city-scale)
You want true geometric separation
Simple, clean code is important

When to use varying line weights

You want the simplest possible implementation
You prefer routes to stay visually grouped
Performance is critical (no geometry processing)
You cannot add external dependencies

When to use leaflet-polylineoffset

You need pixel-perfect control over visual spacing
You are already using the plugin for other purposes
You want consistent screen-space separation regardless of zoom

Tip: For most use cases, we recommend Turf.js lineOffset. It provides the cleanest visual separation with moderate complexity. Use varying line weights when simplicity is paramount. Use leaflet-polylineoffset only if you need precise pixel-level control.

Explore the Demos

All three demos show four routes from Paris landmarks to the Arc de Triomphe. You can:

Toggle individual routes on/off using checkboxes
Click a route to zoom and see details
Compare how each approach handles overlapping segments

Turf.js lineOffset Demo

Varying Line Weights Demo

leaflet-polylineoffset Demo

Summary

Displaying multiple overlapping routes on a map is a common challenge. We explored three practical solutions:

Turf.js lineOffset - Creates geometrically parallel routes by shifting each path perpendicular to its direction. Best for clear visual separation and clean code.
Varying line weights - Uses different line thicknesses to create a layered effect. Simplest implementation with no dependencies.
leaflet-polylineoffset - Pixel-based visual offset. More complex but offers precise screen-space control.

All three approaches work well with the Geoapify Routing API and Leaflet. For most use cases, we recommend Turf.js lineOffset as the best balance of simplicity and visual clarity.

Key takeaways:

Overlapping routes need visual separation to be useful
Geometric offset (Turf.js) creates truly parallel paths
Line weight layering is simplest but less distinct
Pixel offset offers precise control but adds complexity
Custom markers help users match routes to origins

Useful links:

FAQ

Q: Can I use these techniques with MapLibre GL instead of Leaflet?
A: MapLibre GL has built-in support for line offset via the line-offset paint property. This is actually the easiest solution if you are using MapLibre GL. Check the MapLibre GL documentation for examples.

Q: How do I choose the right offset distance?
A: It depends on your typical zoom level and route lengths. For city-scale routes (1-5 km), 10-20 meters works well. For longer routes, you may need larger offsets. Test at your expected zoom levels.

Q: What if routes cross each other after offsetting?
A: This can happen at intersections or when routes approach from opposite directions. The offset is perpendicular to the route direction, so crossing points may shift. In practice, this is rarely a problem for typical use cases.

Q: Can I animate route drawing?
A: Yes, but that is a separate topic. You would need to progressively reveal the polyline coordinates. All three approaches support this, but the implementation is beyond this tutorial's scope.

Q: How many routes can I display before performance suffers?
A: Leaflet handles dozens of routes well. The Turf.js approach adds some processing overhead, but it is negligible for typical use cases (under 20 routes). For hundreds of routes, consider server-side simplification or clustering.

Q: Can I combine multiple approaches?
A: Technically yes, but it is usually unnecessary. Pick one approach based on your requirements. Combining them adds complexity without clear benefit.

Try It Now

Please sign up at geoapify.com and generate your own API key to start building multi-route visualizations.

How to Visualize and Style Routes on a Leaflet Map

Casey Rivers — Mon, 02 Mar 2026 13:29:44 +0000

Displaying a route on a map is straightforward. Making it look good takes more thought. A plain blue line works, but professional applications use shadows, custom colors, and polished markers to create routes that stand out and communicate clearly.

Route styling impacts both aesthetics and usability. The right combination of line weight, shadows, and marker design helps users quickly understand the path while keeping the underlying map readable.

This tutorial walks through building a route visualization with interactive styling controls. You will see how each parameter affects the result and learn the techniques to create professional-looking routes in your own applications.

APIs used:

Routing API - calculate route between waypoints
Map Tiles API - base map layer
Map Marker Icon API - custom waypoint markers

What you will learn:

How to render route GeoJSON on a Leaflet map
Techniques for adding shadows and outlines to route lines
Using custom panes for proper layer ordering
Creating markers with the Map Marker Icon API
Building interactive controls to experiment with styling

The Goal: Professional Route Styling
Set Up the Map
Fetch the Route
Render the Route with Styling
Add Route Shadows
Create Custom Markers
Build Interactive Controls
Explore the Demo
Summary
FAQ

The Goal: Professional Route Styling

A well-styled route has several characteristics:

Visible at all zoom levels: Not too thin to see, not too thick to obscure the map
Clear boundaries: A shadow or outline separates the route from the map
Consistent appearance: Rounded line caps and joins for smooth corners
Informative markers: Numbered waypoints that match the route style

The demo provides controls to adjust all these parameters. This lets you experiment and find the right balance for your use case.

Set Up the Map

Initialize a Leaflet map and create custom panes for layer ordering. Panes control the z-index, ensuring the shadow appears below the route line.

const map = L.map("map", {zoomControl: false}).setView([48.8606, 2.3376], 13);
L.control.zoom({position: "bottomright"}).addTo(map);

// Custom panes for proper z-index layering (shadow below route)
map.createPane("route-shadow");
map.getPane("route-shadow").style.zIndex = 399;
map.createPane("route-line");
map.getPane("route-line").style.zIndex = 400;

// Geoapify map tiles
L.tileLayer(`https://maps.geoapify.com/v1/tile/osm-bright/{z}/{x}/{y}@2x.png?apiKey=${API_KEY}`, {
    attribution: '© <a href="https://www.geoapify.com/">Geoapify</a> © OpenMapTiles © OpenStreetMap',
    maxZoom: 20
}).addTo(map);

Without custom panes, the shadow might appear above the route depending on the order layers are added.

Key: Sign up at geoapify.com to get your API key.

Fetch the Route

The Routing API accepts waypoints as lat,lon pairs separated by |. It returns GeoJSON that Leaflet can render directly.

// Build routing URL (waypoint format: lat,lon separated by |)
const routingUrl = `https://api.geoapify.com/v1/routing?waypoints=${waypoints.map(w => `${w.lat},${w.lon}`).join("|")}&mode=drive&apiKey=${API_KEY}`;

function fetchRoute() {
    fetch(routingUrl)
        .then(res => res.json())
        .then(data => {
            if (data.features?.length > 0) {
                routeFeature = data.features[0];
                renderRoute(routeFeature);
                renderMarkers();
                fitBounds();
            }
        });
}

We store the route feature in routeFeature so we can re-render it when styling changes without fetching again.

Render the Route with Styling

Render the route using L.geoJSON() with styling options:

routeLayer = L.geoJSON(feature, {
    pane: "route-line",
    style: {
        color: routeColor,
        weight: routeWidth,
        opacity: routeOpacity,
        lineCap: "round",
        lineJoin: "round"
    }
}).addTo(map);

Key styling properties:

color: Line color (hex value)
weight: Line thickness in pixels
opacity: Transparency (0-1)
lineCap/lineJoin: Use "round" for smooth ends and corners

Here's how the route looks with and without shadow applied:

Add Route Shadows

Shadows create depth and help the route stand out. Draw a wider, darker line behind the main route:

shadowLayer = L.geoJSON(feature, {
    pane: "route-shadow",
    style: {
        color: shadowColor,
        weight: routeWidth + 4,
        opacity: shadowOpacity,
        lineCap: "round",
        lineJoin: "round"
    }
}).addTo(map);

The shadow is 4 pixels wider than the route (2 pixels on each side). Using a separate pane guarantees it renders below the main route.

Tip: Semi-transparent black works well on most map styles. For dark maps, try a lighter shadow color.

Create Custom Markers

The Map Marker Icon API generates marker images on the fly. Create numbered markers with custom colors:

const icon = L.icon({
    iconUrl: `https://api.geoapify.com/v2/icon?type=awesome&color=${color}&text=${number}&size=${size}&scaleFactor=2&apiKey=${API_KEY}`,
    iconSize: [size * 0.75, size],
    iconAnchor: [size * 0.375, size - 3],
    popupAnchor: [0, -size + 5]
});

const marker = L.marker([wp.lat, wp.lon], {icon})
    .bindPopup(`<strong>${wp.name}</strong><br>Waypoint ${idx + 1}`)
    .addTo(map);

Three marker types are available:

awesome: Classic map pin shape
material: Google Maps style pin
circle: Simple circle marker

The scaleFactor=2 parameter provides high-resolution icons for retina displays.

Build Interactive Controls

Each control updates the route or markers in real-time by calling the render functions:

document.getElementById("route-color").addEventListener("input", (e) => {
    document.getElementById("route-color-value").textContent = e.target.value.toUpperCase();
    if (routeFeature) renderRoute(routeFeature);
});

document.getElementById("marker-type").addEventListener("change", renderMarkers);

The pattern is simple: listen for input changes, update the displayed value, and re-render the affected layer.

Explore the Demo

The interactive demo lets you experiment with all styling parameters in real-time. Try adjusting:

Route styling - color, width, and opacity
Shadow effects - toggle, color, and opacity
Marker types - awesome pins, material pins, or circles
Marker size - from 32px to 80px
Shadow toggle - for both routes and markers

Play with different combinations to find what works best for your application. The reset button restores default settings.

👉 Try the live demo:

Summary

Visualizing routes on a Leaflet map involves more than just drawing a line. This tutorial covered:

Custom panes for controlling layer order (shadow below route)
Route styling with color, width, opacity, and line caps
Shadow technique using a wider, darker line behind the main route
Map Marker Icon API for customizable waypoint markers
Interactive controls for experimenting with parameters

Recommended settings for most applications:

Route width: 5-8 pixels
Shadow: 3-4 pixels wider than route, 0.2-0.4 opacity
Line caps: "round" for smooth appearance
Marker size: 40-56 pixels depending on map zoom

Key takeaways:

Custom panes guarantee consistent layer ordering
Shadows add depth and improve route visibility
The Map Marker Icon API provides flexible marker customization
Rounded line caps and joins create professional-looking routes
Interactive controls help find the right balance for your use case

Useful links:

FAQ

Q: What's the difference between shadow and outline?

A: Shadow is a wider line drawn behind the route with lower opacity, creating a soft depth effect. Outline would be a border around the route line. In this tutorial, we use the shadow technique as it provides better visual separation on most map styles.

Q: Why use custom panes instead of z-index?

A: Leaflet's pane system provides explicit control over layer ordering regardless of when layers are added to the map. With z-index, layer order can depend on add order, leading to unpredictable results. Custom panes guarantee the shadow always renders below the route.

Q: How do I choose the right route color?

A: Consider contrast with your map tiles. Blue (#2196F3) works well on most map styles. For dark maps, use brighter colors. Avoid red or orange as they often indicate traffic or warnings. Test at different zoom levels to ensure visibility.

Q: Can I animate the route drawing?

A: Yes, but that requires a different approach. You would progressively reveal the route by creating polylines with increasing coordinate arrays or using CSS animations on SVG paths. The GeoJSON approach shown here is not optimized for animation.

Q: How many waypoints can I display before performance suffers?

A: Leaflet handles dozens of markers well. For the route itself, complexity depends on the number of coordinate points, not waypoints. Routes with thousands of points may benefit from simplification using libraries like Turf.js.

Q: Can I style different segments of the route differently?

A: Yes. Split the route GeoJSON into separate features and render each with different styles. This is useful for highlighting specific segments, showing traffic conditions, or indicating different transportation modes.

Q: How do I make routes clickable?

A: Add event listeners to the route layer. For example: routeLayer.on('click', function(e) { ... }). You can show popups, highlight the route, or trigger other actions.

Try It Now

👉 Open the Live Demo

How to Collect Route Waypoints with Address Autocomplete and Map Clicks

Casey Rivers — Mon, 23 Feb 2026 06:10:33 +0000

Ever tried typing "that coffee shop near the park" into a route planner? It does not work. Users know where they want to go, but they do not always know the exact address. Sometimes they want to type "Arc de Triomphe" and pick from suggestions. Other times they just want to click on the map because they recognize the spot visually.

A good waypoint interface supports both. It also needs to handle the inevitable "wait, I want to go there second, not third" moment with easy reordering.

This tutorial walks through building exactly that kind of interface.

What makes a waypoint input actually usable:

Address autocomplete - catches typos, suggests real places
Map clicks with reverse geocoding - click a spot, get the address
Drag and drop reordering - because plans change
Numbered markers - visual confirmation of what was entered

By the end, you will have a waypoint collection interface that handles how people actually enter locations, not how we wish they would.

Try the live demo:

APIs used:

Address Autocomplete API - address suggestions as you type
Reverse Geocoding API - convert map clicks to addresses
Map Tiles API - base map layer
Map Marker Icon API - numbered waypoint markers
Routing API - calculate route between waypoints

The Challenge: Multiple Input Methods
Set Up the HTML Structure
Initialize the Map
Add Address Autocomplete
Handle Map Clicks with Reverse Geocoding
Implement Drag and Drop Reordering
Display Numbered Markers
Build the Route
Theme Support
Summary

The Challenge: Multiple Input Methods

Route planning applications need to accept waypoints in different ways. Some users prefer typing addresses and selecting from suggestions. Others want to click directly on the map, especially when they know the location visually but not the exact address. The ideal solution supports both methods seamlessly.

When a user clicks the map, we need to convert those coordinates into a meaningful address. This is called reverse geocoding. The address then appears in the input field, so users can see exactly what location they selected.

Waypoint order matters for routing. Users often need to rearrange stops after adding them. Drag and drop provides an intuitive way to reorder without deleting and re-adding waypoints.

Set Up the HTML Structure

The interface has two main areas: a side panel with waypoint inputs and the map. Load the required libraries:

<link rel="stylesheet" href="https://unpkg.com/leaflet@1.9.4/dist/leaflet.css">
<link id="geocoder-theme" rel="stylesheet"
      href="https://cdn.jsdelivr.net/npm/@geoapify/geocoder-autocomplete@3.0.1/styles/minimal.css">

<script src="https://unpkg.com/leaflet@1.9.4/dist/leaflet.js"></script>
<script src="https://cdn.jsdelivr.net/npm/@geoapify/geocoder-autocomplete@3.0.1/dist/index.min.js"></script>

Create the container for waypoint inputs and the map:

<div class="panel">
  <h3>Collect Waypoints</h3>
  <p class="hint">Enter addresses or click on the map. Drag rows to reorder.</p>
  <div id="waypoints"></div>
  <button id="add-btn">Add a new location</button>
  <button id="build-route-btn">Build Route</button>
</div>

<div id="map"></div>

The geocoder-autocomplete library provides pre-built CSS themes (minimal, round-borders, and their dark variants).

Key: Sign up at geoapify.com to get your API key.

Initialize the Map

Set up a Leaflet map and initialize the waypoints array:

const API_KEY = "YOUR_API_KEY";

let waypoints = [];
let activeIdx = 0;

const map = L.map("map", {zoomControl: false}).setView([48.8566, 2.3522], 12);
L.control.zoom({position: "bottomright"}).addTo(map);

L.tileLayer(`https://maps.geoapify.com/v1/tile/osm-bright/{z}/{x}/{y}@2x.png?apiKey=${API_KEY}`, {
    attribution: '© Geoapify © OpenMapTiles © OpenStreetMap',
    maxZoom: 20
}).addTo(map);

// Initialize with 2 empty waypoints
addWaypoint();
addWaypoint();

The waypoints array stores coordinates, formatted address, marker reference, and autocomplete instance for each waypoint.

Add Address Autocomplete

The @geoapify/geocoder-autocomplete library handles address suggestions. When a user types, it queries the Address Autocomplete API and displays matching addresses.

Create an autocomplete instance for each waypoint input:

function renderList() {
    waypoints.forEach((wp, idx) => {
        // ... create row HTML with container element id="ac-${idx}" ...

        // Setup autocomplete
        wp.autocomplete = new autocomplete.GeocoderAutocomplete(
            document.getElementById(`ac-${idx}`), 
            API_KEY, 
            {placeholder: "Enter address"}
        );

        wp.autocomplete.on("select", (loc) => {
            if (loc) {
                setWaypoint(idx, loc.properties.lat, loc.properties.lon, loc.properties.formatted);
            }
        });
    });
}

The select event fires when a user picks a suggestion, providing coordinates and formatted address.

Tip: The library supports multiple themes (minimal, round-borders, and their dark variants). You can switch themes by changing the CSS file loaded in the head.

Handle Map Clicks with Reverse Geocoding

When users click the map, we call the Reverse Geocoding API to convert coordinates to an address. The result fills the first empty waypoint input.

// Map click → reverse geocode → fill first empty waypoint
map.on("click", async (e) => {
    if (activeIdx < 0) return;

    const {lat, lng} = e.latlng;
    const res = await fetch(`https://api.geoapify.com/v1/geocode/reverse?lat=${lat}&lon=${lng}&apiKey=${API_KEY}`);
    const data = await res.json();

    if (data.features?.[0]) {
        const p = data.features[0].properties;
        setWaypoint(activeIdx, p.lat, p.lon, p.formatted);
    }
});

The activeIdx tracks which waypoint should receive the next map click. It points to the first empty waypoint, or -1 if all waypoints have values.

// Find first empty waypoint
function updateActiveIdx() {
    activeIdx = waypoints.findIndex(wp => !wp.lat);
    waypoints.forEach((wp, idx) => {
        const input = document.querySelector(`#ac-${idx} input`);
        if (input) input.placeholder = idx === activeIdx ? "Enter address or click map" : "Enter address";
    });
}

The placeholder text changes to indicate which input will receive the next map click.

Implement Drag and Drop Reordering

HTML5 drag and drop lets users reorder waypoints. The key is handling the drop event to reorder the array:

row.draggable = true;

row.ondragstart = (e) => {
    e.dataTransfer.setData("idx", idx);
};

row.ondrop = (e) => {
    e.preventDefault();
    const from = +e.dataTransfer.getData("idx");
    if (from !== idx) {
        waypoints.splice(idx, 0, waypoints.splice(from, 1)[0]);
        renderList();
    }
};

row.ondragover = (e) => e.preventDefault(); // Allow drop

When dropped, we use splice to move the waypoint in the array, then re-render. This updates marker numbers and colors to match the new order.

Display Numbered Markers

Each waypoint gets a numbered marker using the Map Marker Icon API:

function updateMarker(idx) {
    const wp = waypoints[idx];
    if (wp.marker) map.removeLayer(wp.marker);
    if (!wp.lat) return;

    const color = getColor(idx).replace('#', '%23');
    const icon = L.icon({
        iconUrl: `https://api.geoapify.com/v2/icon?type=awesome&color=${color}&text=${idx + 1}&size=48&contentSize=20&scaleFactor=2&apiKey=${API_KEY}`,
        iconSize: [36, 48],
        iconAnchor: [18, 48],
        popupAnchor: [0, -48]
    });

    wp.marker = L.marker([wp.lat, wp.lon], {icon, draggable: true}).addTo(map).bindPopup(wp.formatted);

    // Drag marker → reverse geocode
    wp.marker.on("dragend", async () => {
        const {lat, lng} = wp.marker.getLatLng();
        const res = await fetch(`https://api.geoapify.com/v1/geocode/reverse?lat=${lat}&lon=${lng}&apiKey=${API_KEY}`);
        const data = await res.json();
        if (data.features?.[0]) {
            const p = data.features[0].properties;
            wp.lat = p.lat;
            wp.lon = p.lon;
            wp.formatted = p.formatted;
            wp.autocomplete.setValue(p.formatted);
            wp.marker.setPopupContent(p.formatted);
            clearRoute();
        }
    });
}

Tip: The scaleFactor=2 parameter provides high-resolution icons for retina displays.

Build the Route

Once waypoints are set, call the Routing API:

async function buildRoute() {
    const validWaypoints = waypoints.filter(wp => wp.lat && wp.lon);

    if (validWaypoints.length < 2) {
        alert("Please add at least 2 waypoints to build a route");
        return;
    }

    const waypointsParam = validWaypoints.map(wp => `${wp.lat},${wp.lon}`).join("|");
    const url = `https://api.geoapify.com/v1/routing?waypoints=${waypointsParam}&mode=drive&apiKey=${API_KEY}`;

    const res = await fetch(url);
    const data = await res.json();

    if (data.features?.[0]) {
        renderRoute(data.features[0]);
    }
}

Render the route as a GeoJSON layer:

function renderRoute(feature) {
    clearRoute();

    routeLayer = L.geoJSON(feature, {
        style: {
            color: "#2196F3",
            weight: 6,
            opacity: 0.8,
            lineCap: "round",
            lineJoin: "round"
        }
    }).addTo(map);

    map.fitBounds(routeLayer.getBounds(), {padding: [50, 50]});
}

Theme Support

The demo includes light and dark themes. Switch themes by changing the CSS file:

function setTheme(name) {
    document.getElementById("geocoder-theme").href =
        `https://cdn.jsdelivr.net/npm/@geoapify/geocoder-autocomplete@3.0.1/styles/${name}.css`;
    document.body.className = `theme-${name}`;
    setMapTiles(name.includes("dark") ? "dark" : "light");
    localStorage.setItem("theme", name);
}

The preference is saved to localStorage so users see their chosen theme on return visits.

Summary

Collecting route waypoints requires combining multiple input methods for the best user experience. This tutorial showed how to:

Set up address autocomplete using the @geoapify/geocoder-autocomplete library with customizable themes
Handle map clicks by reverse geocoding coordinates to addresses
Implement drag and drop for intuitive waypoint reordering
Display numbered markers that update dynamically as waypoints change
Build routes from collected waypoints using the Routing API

The combination of autocomplete and map clicks covers different user preferences. Some users know exact addresses; others recognize locations visually. Supporting both makes your route planner accessible to everyone.

Key takeaways:

Address autocomplete reduces errors and speeds up input
Reverse geocoding converts map clicks to meaningful addresses
Drag and drop provides intuitive reordering without complex UI
Numbered markers help users track waypoint order
Theme support improves accessibility and user preference

Useful links:

Try It Now

Printable Route Directions with Geoapify: Complete Demo Walkthrough

Casey Rivers — Tue, 17 Feb 2026 08:30:07 +0000

This is the final tutorial in our series on building printable route directions. The full example is available on GitHub:

👉 Printable route directions example

In the previous tutorials, we covered each piece separately: requesting routes and directions, generating route overview images, creating step preview maps, and adding elevation profiles. Now let's see how all these pieces come together in a complete working demo.

When we first built the printable directions demo, we wanted to answer a common question: how do you create route directions that users can actually print and take with them? Navigation apps are great when you have a phone, but delivery drivers, hikers, and event organizers often need paper directions they can hand out or use offline. This demo shows one way to solve that problem.

Try the live demo:

➡️ View on CodePen

APIs and Libraries used:

Routing API - calculate routes with elevation data
Static Maps API - generate route preview images
Map Tiles - Leaflet base map
Leaflet - interactive map
Chart.js - elevation profile
Turf.js - geometry calculations for step previews

What you will learn:

How to structure a complete routing application
Combining interactive and static map elements
Building a print-ready layout
Connecting all the pieces from the series

Demo Overview
Application Structure
Waypoint Management
Route Calculation
Static Route Preview
Turn-by-Turn Directions
Elevation Profile
Explore the Demo
Summary
FAQ

Demo Overview

The complete demo lets users plan a route by clicking on a map, then generates everything needed for printable directions:

Interactive map for adding waypoints
Static route preview showing the full route
Turn-by-turn directions with step preview images
Elevation profile chart
Print button for generating a clean printout

Application Structure

The demo maintains state for waypoints, markers, the route layer, and the chart instance:

let waypoints = [];
let markers = [];
let routeLayer = null;
let chartInstance = null;

The Leaflet map is initialized with Geoapify tiles:

const map = L.map("map", {zoomControl: false}).setView([48.8566, 2.3522], 6);
L.control.zoom({position: "bottomright"}).addTo(map);

L.tileLayer(`https://maps.geoapify.com/v1/tile/osm-bright/{z}/{x}/{y}@2x.png?apiKey=${apiKey}`, {
  attribution: '© <a href="https://www.geoapify.com/">Geoapify</a> © OpenMapTiles © OpenStreetMap',
  maxZoom: 20
}).addTo(map);

When users click on the map, a waypoint is added:

map.on("click", async (e) => {
  addWaypoint(e.latlng.lat, e.latlng.lng);
});

Waypoint Management

The addWaypoint function stores the coordinates and triggers a route calculation when there are at least two points:

function addWaypoint(lat, lon) {
  waypoints.push({lat, lon});
  updateWaypointList();
  updateMarkers();

  if (waypoints.length >= 2) {
    calculateRoute();
  }
}

Markers use the Geoapify Icon API with different colors for start, end, and intermediate points:

function updateMarkers() {
  markers.forEach(m => m.remove());
  markers = [];

  waypoints.forEach((wp, i) => {
    const color = i === 0 ? "%2343A047" : i === waypoints.length - 1 ? "%23E91E63" : "%232196F3";
    const icon = i === 0 ? "circle" : i === waypoints.length - 1 ? "flag" : "circle";

    markers.push(L.marker([wp.lat, wp.lon], {
      icon: L.icon({
        iconUrl: `https://api.geoapify.com/v2/icon?type=awesome&color=${color}&icon=${icon}&size=48&scaleFactor=2&apiKey=${apiKey}`,
        iconSize: [36, 48],
        iconAnchor: [18, 48]
      })
    }).addTo(map));
  });

  if (waypoints.length > 1) {
    map.fitBounds(waypoints.map(wp => [wp.lat, wp.lon]), {padding: [50, 50]});
  }
}

💡 Visual feedback

Green for start, red for destination, and blue for intermediate stops. This color coding helps users understand the route at a glance.

Different marker colors help users quickly identify start, end, and intermediate waypoints.

Route Calculation

The route request includes details=elevation to get elevation data along with the route:

async function calculateRoute() {
  const waypointsParam = waypoints.map(wp => `${wp.lat},${wp.lon}`).join("|");
  const url = `https://api.geoapify.com/v1/routing?waypoints=${waypointsParam}&mode=drive&details=elevation&apiKey=${apiKey}`;

  try {
    const response = await fetch(url);
    const data = await response.json();

    if (!data.features || data.features.length === 0) {
      alert("No route found");
      return;
    }

    const route = data.features[0];
    drawRoute(route);
    generateStaticPreview(route);
    displayRouteSummary(route);
    generateDirections(route);
    drawElevation(route);

    document.getElementById("results").classList.remove("hidden");
  } catch (error) {
    console.error("Error calculating route:", error);
    alert("Failed to calculate route");
  }
}

Once we have the route, we call five functions to update different parts of the UI. This separation keeps each piece focused and testable.

💡 Modular design

Each function handles one responsibility. If you only need the static preview, you can use generateStaticPreview without the elevation chart. This modularity came from our own experience: different projects needed different combinations of these features.

The route is drawn on the interactive map with Leaflet's GeoJSON layer:

function drawRoute(geojson) {
  if (routeLayer) map.removeLayer(routeLayer);
  routeLayer = L.geoJSON(geojson, {
    style: {color: "#3498db", weight: 5, opacity: 0.8}
  }).addTo(map);
}

Static Route Preview

The static preview uses the same technique from Part 2 of the series. We send a POST request with the route GeoJSON:

async function generateStaticPreview(geojson) {
  geojson.properties.linecolor = "#3498db";
  geojson.properties.linewidth = "5";

  const response = await fetch(`https://maps.geoapify.com/v1/staticmap?apiKey=${apiKey}`, {
    method: "POST",
    headers: {"Content-Type": "application/json"},
    body: JSON.stringify({
      style: "osm-bright",
      width: 800,
      height: 250,
      scaleFactor: 2,
      geojson: geojson,
      markers: geojson.properties.waypoints.map(wp => ({
        lat: wp.location[1],
        lon: wp.location[0],
        color: "#ff0000",
        size: "medium"
      }))
    })
  });

  const blob = await response.blob();
  document.getElementById("route-preview").src = URL.createObjectURL(blob);
}

The API automatically calculates the bounding box to fit the entire route. The resulting image is displayed directly in the page and will be included when the user prints.

ℹ️ Why use URL.createObjectURL?

Converting the blob to an object URL lets us display the image without saving it to a server. This keeps everything client-side and avoids extra infrastructure. The URL is valid until the page is closed or you call URL.revokeObjectURL().

The static preview gives users a printable overview of their route.

Turn-by-Turn Directions

Each step in the route gets a direction card with text and a preview image. The generateDirections function builds the HTML:

function generateDirections(geojson) {
  let html = "";

  geojson.properties.legs.forEach((leg, legIndex) => {
    leg.steps.forEach((step, i) => {
      const dist = step.distance >= 1000 
        ? `${(step.distance / 1000).toFixed(1)} km` 
        : `${Math.round(step.distance)} m`;

      const previewUrl = generateStepPreviewUrl(legIndex, step, geojson.geometry.coordinates);

      html += `
        <div class="direction-step">
          <div class="step-number">${i + 1}</div>
          <div class="step-content">
            <div class="step-instruction">${step.instruction.text}</div>
            <div class="step-meta">${dist}</div>
          </div>
          <div class="step-preview-container loading" data-url="${previewUrl}" data-step="${i + 1}"></div>
        </div>
      `;
    });
  });

  document.getElementById("directions").innerHTML = html;

  // Load images with animation
  document.querySelectorAll('.step-preview-container').forEach(container => {
    const img = new Image();
    img.onload = () => {
      container.classList.remove('loading');
      img.className = 'step-preview';
      container.innerHTML = '';
      container.appendChild(img);
    };
    img.alt = `Step ${container.dataset.step}`;
    img.src = container.dataset.url;
  });
}

The step preview URLs are generated using the technique from Part 3. Each preview shows the past route (gray), next route (pink), and the maneuver itself (white with black border):

function generateStepPreviewUrl(legIndex, step, coordinates) {
  const coords = coordinates[legIndex];
  const turnCoordinate = coords[step.from_index];
  const markerCoordinates = `${turnCoordinate[0]},${turnCoordinate[1]}`;

  // Check if it's a start or finish step
  const isStart = ["StartAt", "StartAtRight", "StartAtLeft"].includes(step.instruction.type);
  const isFinish = ["DestinationReached", "DestinationReachedRight", "DestinationReachedLeft"].includes(step.instruction.type);

  // Extract coordinate segments with direction arrow
  const past = getRelatedCoordinates(coords, step, 'past');
  const next = getRelatedCoordinates(coords, step, 'next');
  const maneuver = getRelatedCoordinates(coords, step, 'manoeuvre');
  const maneuverArrow = getRelatedCoordinates(coords, step, 'manoeuvre-arrow');

  // Build geometries array
  const geometries = [];

  if (!isStart) {
    geometries.push(`polyline:${past};linewidth:5;linecolor:${encodeURIComponent('#ad9aad')}`);
  }

  if (!isFinish) {
    geometries.push(`polyline:${next};linewidth:5;linecolor:${encodeURIComponent('#eb44ea')}`);
  }

  if (!isFinish) {
    geometries.push(`polyline:${maneuver};linewidth:7;linecolor:${encodeURIComponent('#333333')};lineopacity:1`);
    geometries.push(`polyline:${maneuver};linewidth:5;linecolor:${encodeURIComponent('#ffffff')};lineopacity:1`);
    geometries.push(`polygon:${maneuverArrow};linewidth:1;linecolor:${encodeURIComponent('#333333')};lineopacity:1;fillcolor:${encodeURIComponent('#ffffff')};fillopacity:1`);
  }

  // Calculate bearing
  const bearing = getBearing(coords, step) + 180;

  // Add finish marker if needed
  const icon = isFinish ? `&marker=lonlat:${markerCoordinates};type:material;color:%23539de4;icon:flag-checkered;icontype:awesome;whitecircle:no` : '';

  return `https://maps.geoapify.com/v1/staticmap?style=osm-bright&width=250&height=150&apiKey=${apiKey}&geometry=${geometries.join('|')}&center=lonlat:${markerCoordinates}&zoom=16&scaleFactor=2&bearing=${bearing}&pitch=45${icon}`;
}

ℹ️ Loading states

The demo shows a loading spinner while step preview images load. This provides feedback to users, especially on slower connections where generating multiple static map images takes time.

Each direction step includes a preview image showing the turn context with color-coded route segments.

Elevation Profile

The elevation chart uses Chart.js with the data from the routing response:

function drawElevation(geojson) {
  if (chartInstance) chartInstance.destroy();

  const elevation = geojson.properties.legs[0].elevation_range;
  if (!elevation || elevation.length === 0) {
    document.getElementById("elevation-section").classList.add("hidden");
    return;
  }

  document.getElementById("elevation-section").classList.remove("hidden");

  chartInstance = new Chart(document.getElementById("elevation-chart"), {
    type: "line",
    data: {
      labels: elevation.map(p => p[0]),
      datasets: [{
        data: elevation.map(p => p[1]),
        borderColor: "#3498db",
        backgroundColor: "rgba(52, 152, 219, 0.2)",
        fill: true,
        tension: 0.4,
        pointRadius: 0
      }]
    },
    options: {
      animation: false,
      responsive: true,
      maintainAspectRatio: false,
      scales: {
        x: {
          type: 'linear',
          title: {display: true, text: "Distance (m)"}
        },
        y: {
          type: 'linear',
          beginAtZero: true,
          title: {display: true, text: "Elevation (m)"}
        }
      },
      plugins: {
        legend: {display: false},
        tooltip: {
          displayColors: false,
          callbacks: {
            title: (tooltipItems) => `Distance: ${tooltipItems[0].label}m`,
            label: (tooltipItem) => `Elevation: ${tooltipItem.raw}m`
          }
        }
      }
    }
  });
}

💡 Handling missing elevation data

Not all routes have elevation data (depends on the travel mode). The demo checks if elevation_range exists and hides the elevation section if it's not available.

The elevation profile helps users understand the terrain along the route.

Explore the Demo

The live CodePen demo lets you:

Click on the map to add waypoints
See the route calculated automatically
View the static preview, directions, and elevation chart
Click "Print Directions" to generate a print-ready page

Experiment with the code

Change the mode parameter from drive to walk or bicycle
Adjust the static map dimensions for different layouts
Modify the step preview colors
Try different map styles (dark-matter, positron)

Print styles

The demo includes CSS for print output:

@media print {
  body {
    padding: 0;
    background: white;
  }

  .map-controls,
  .btn-print {
    display: none !important;
  }

  .result-section {
    page-break-inside: avoid;
  }
}

This hides the interactive elements and keeps the printable content clean.

💡 Print testing tip

Use your browser's print preview (Ctrl/Cmd + P) to test the layout without wasting paper. Chrome's DevTools also has a "Rendering" panel where you can emulate print media to see how styles apply.

Summary

This demo brings together everything from the series:

Routing API for route calculation and turn-by-turn instructions (Part 1)
Static Maps API for the route overview image (Part 2)
Step preview images with bearing and pitch (Part 3)
Elevation profile with Chart.js (Part 4)
Print-ready layout with CSS media queries

The key insight is that each piece works independently. You can use just the static preview, or just the elevation chart, or combine them as shown here. The modular approach makes it easy to adapt for your specific needs.

We found this structure useful because different clients had different requirements: some wanted just the route overview for confirmation emails, others needed full printable directions for field workers. By keeping the pieces separate, we could mix and match without rewriting code.

Series links:

Part 1: Requesting routes and turn-by-turn directions
Part 2: Generating route overview images
Part 3: Creating step preview maps
Part 4: Adding elevation profiles

Useful links:

FAQ

Q: Can I use this code in production?

A: Yes. The code is open source. Replace the demo API key with your own from myprojects.geoapify.com.

Q: How do I deploy this demo?

A: The demo is pure HTML, CSS, and JavaScript. Host it on any static server: GitHub Pages, Netlify, Vercel, or your own server.

Q: Does it work offline?

A: Route calculation requires internet connectivity. However, once generated, you can save or print the static images and directions for offline viewing.

Q: Can I add more than 2 waypoints?

A: Yes. The demo supports multiple waypoints. The Routing API calculates multi-leg routes automatically.

Q: How do I customize the print output?

A: Edit the CSS @media print rules. You can adjust fonts, hide sections, or change the layout for different paper sizes.

Q: Can I use this with React, Vue, or Angular?

A: Yes. The core functions (generateStaticPreview, generateDirections, drawElevation) are framework-agnostic. Extract them and integrate into your component structure.

Try It Now

👉 Open the Live Demo

Please sign up at geoapify.com and generate your own API key to start building printable route directions.

How to Create a Route Elevation Profile with Chart.js and Geoapify Routing API

Casey Rivers — Mon, 09 Feb 2026 14:03:21 +0000

This is the fourth tutorial in our series on building printable route directions. The full example is available on GitHub:

👉 Printable route directions example

In the previous tutorials, we covered requesting routes and directions, generating route overview images, and creating step preview maps. Now we add the final piece: elevation profiles.

Elevation data transforms a flat route into something more meaningful. A 10 km hike looks very different if it's flat vs. climbing 500 meters. Cyclists care about this, hikers care about this, and even drivers benefit from knowing about steep grades that affect fuel consumption or travel time.

When we built the printable directions demo, we wanted to include an elevation chart that gives users a quick visual sense of the terrain. In this tutorial, you'll learn how to extract elevation data from the Routing API and render it as a clean, responsive chart using Chart.js.

Try the live demo:

➡️ View on CodePen

APIs and Libraries:

Routing API - get elevation data with routes
Chart.js - render the elevation chart

What you will learn:

Request elevation data from the Routing API
Extract elevation points from the response
Optimize data for chart performance
Render a smooth elevation profile with Chart.js

Request Elevation Data
Extract Elevation Points
Optimize the Data
Render with Chart.js
Explore the Demo
Summary
FAQ

Step 1: Request Elevation Data

The Routing API includes elevation data when you add details=elevation to the request. This is an optional detail. If you don't need elevation, skip it to reduce response size.

const waypoints = "48.1351,11.5820|52.5200,13.4050"; // Munich to Berlin

// Add details=elevation to get elevation data
const routingUrl = `https://api.geoapify.com/v1/routing?waypoints=${waypoints}&mode=drive&details=elevation&apiKey=${apiKey}`;

const response = await fetch(routingUrl);
const data = await response.json();
const route = data.features[0];

The response includes elevation_range in each leg:

{
  "features": [{
    "properties": {
      "distance": 585050,
      "time": 20454.257,
      "legs": [{
        "elevation_range": [
          [0, 513.7],                    // [distance in meters, elevation in meters]
          [7.17, 513.98],
          [23.15, 514.62],
          [31.12, 515.02],
          // ... thousands more points ...
          [584383.17, 39.32]
        ]
      }]
    }
  }]
}

Each elevation_range array contains [distance, elevation] pairs for points along the route.

ℹ️ Combining details

You can request multiple details in one call: details=elevation,instruction_details. This is more efficient than making separate requests if you need both elevation and turn-by-turn instructions.

Step 2: Extract Elevation Points

Loop through all legs and collect elevation data:

function calculateElevationProfileData(routeData) {
  const legElevations = [];

  // Collect elevation ranges from each leg
  routeData.properties.legs.forEach(leg => {
    if (leg.elevation_range) {
      legElevations.push(leg.elevation_range);
    } else {
      legElevations.push([]);
    }
  });

  let labels = [];  // Distances
  let data = [];    // Elevations

  // Combine data from all legs
  legElevations.forEach((legElevation, index) => {
    // Calculate cumulative distance across legs
    let previousLegsDistance = 0;
    for (let i = 0; i <= index - 1; i++) {
      previousLegsDistance += legElevations[i][legElevations[i].length - 1][0];
    }

    // Add distances (x-axis)
    labels.push(...legElevation.map(point => point[0] + previousLegsDistance));

    // Add elevations (y-axis)
    data.push(...legElevation.map(point => point[1]));
  });

  return { labels, data };
}

For multi-leg routes (multiple waypoints), we add the distance from previous legs to maintain continuity. This ensures the x-axis shows the total distance traveled, not just the distance within each leg.

💡 Why track cumulative distance?

Without cumulative distance, a multi-leg route would show disconnected segments on the chart. By adding the previous legs' distances, the elevation profile becomes one continuous line from start to finish.

Step 3: Optimize the Data

Long routes can have thousands of elevation points. When we first built the elevation chart, we passed all the data directly to Chart.js, and the browser froze for several seconds on a 500 km route. The lesson: always optimize large datasets before rendering.

The solution is to keep only points that represent significant changes:

// Optimize array size to avoid performance problems
const labelsOptimized = [];
const dataOptimized = [];
const minDist = 5; // 5m
const minHeight = 10; // ~10m

labels.forEach((dist, index) => {
  if (index === 0 || index === labels.length - 1 ||
      (dist - labelsOptimized[labelsOptimized.length - 1]) > minDist ||
      Math.abs(data[index] - dataOptimized[dataOptimized.length - 1]) > minHeight) {
    labelsOptimized.push(dist);
    dataOptimized.push(data[index]);
  }
});

This keeps:

First and last points (always)
Points with significant distance gaps (>5m)
Points with elevation changes (>10m)

A 500km route might reduce from 10,000 points to 800 points, making the chart render instantly.

💡 Tuning the thresholds

The minDist and minHeight values (5m and 10m in our example) work well for most routes. For mountainous terrain, you might increase minHeight to 20-30m to avoid a jagged chart. For flat routes, lower values preserve more detail. Experiment based on your use case.

Step 4: Render with Chart.js

Create a line chart with the elevation data:

const ctx = document.getElementById("elevation-chart").getContext("2d");

const chartData = {
  labels: elevationData.labels,
  datasets: [{
    data: elevationData.data,
    fill: true,
    borderColor: '#66ccff',
    backgroundColor: '#66ccff66',
    tension: 0.1,
    pointRadius: 0,
    spanGaps: true
  }]
};

const config = {
  type: 'line',
  data: chartData,
  options: {
    animation: false,
    maintainAspectRatio: false,
    scales: {
      x: {
        type: 'linear',
        title: {
          display: true,
          text: 'Distance (m)'
        }
      },
      y: {
        type: 'linear',
        beginAtZero: true,
        title: {
          display: true,
          text: 'Elevation (m)'
        }
      }
    },
    plugins: {
      legend: {
        display: false
      },
      tooltip: {
        displayColors: false,
        callbacks: {
          title: (tooltipItems) => {
            return `Distance: ${tooltipItems[0].label}m`;
          },
          label: (tooltipItem) => {
            return `Elevation: ${tooltipItem.raw}m`;
          }
        }
      }
    }
  }
};

const chartInstance = new Chart(ctx, config);

The elevation profile shows hills and valleys along the route. The filled area makes changes easier to see.

ℹ️ Chart.js configuration choices

We disable animation (animation: false) because the chart often updates when users select different routes. Animations in this context feel sluggish rather than smooth. We also hide the legend since there's only one dataset. These are UX decisions, not technical requirements.

Step 5: Explore the Demo

The live CodePen demo shows:

Fetching a route with elevation data
Processing and optimizing elevation points
Rendering with Chart.js
The data structure from the API

Experiment with the code

Open the demo in CodePen and try modifying the JavaScript:

Change waypoints to a mountain route for dramatic elevation changes
Adjust minDist and minHeight thresholds to see optimization effects
Try different chart colors and fill styles

Use cases

Scenario	Why Elevation Matters
Hiking routes	Estimate difficulty and plan breaks
Cycling routes	Account for climbs in time estimates
Running routes	Calculate calorie burn more accurately
Delivery planning	Estimate fuel consumption for trucks
Real estate	Show terrain profiles for property access

Summary

Elevation profiles add valuable context to route directions. They help users understand what they're getting into before they start, whether it's a gentle stroll or a challenging climb.

In this tutorial, you learned how to:

Request elevation data from the Routing API using the details=elevation parameter
Extract elevation points from multiple route legs with cumulative distance tracking
Optimize the dataset to avoid performance issues with large routes
Render an elevation profile with Chart.js using appropriate configuration

This is the fourth tutorial in our series on building printable route directions. The series covers:

Part 1: Requesting routes and turn-by-turn directions
Part 2: Generating route overview images
Part 3: Creating step preview maps
Part 4: Adding elevation profiles (this tutorial)
Part 5: Complete demo walkthrough

In the next tutorial, we'll bring all these pieces together into a complete working demo with an interactive map, printable output, and all the features combined.

The full working example is also available on GitHub:
👉 Printable route directions example

Useful links:

FAQ

Q: Which travel modes support elevation data?

A: Elevation is available for walk, hike, bicycle, mountain_bike, road_bike, and some motorized modes. Check the Routing API documentation for the complete list.

Q: How do I highlight steep sections on the chart?

A: Calculate the grade (rise/run) between points and use Chart.js segment styling to color steep sections differently.

Q: Can I export the chart as an image?

A: Yes. Use Chart.js's built-in toBase64Image() method:

const imageUrl = chart.toBase64Image();
// Use in <img> tag or download

Q: Why optimize the data?

A: A 500km route can have 10,000+ elevation points. Rendering that many points slows down the chart. Optimization reduces to ~800 points while keeping the visual profile accurate.

Q: Can I add markers for waypoints on the elevation chart?

A: Yes. Calculate which distance values correspond to waypoints and add them as a separate dataset with pointStyle: 'triangle'.

What's Next?

In the final part of this series, we'll combine all these techniques into a complete working demo. You'll see how the routing API, static maps, step previews, and elevation charts work together in a single application with print functionality.

👉 Part 5: Printable Route Directions - Complete Demo Walkthrough

Try It Now

👉 Open the Live Demo

Please sign up at geoapify.com and generate your own API key to start adding elevation profiles to your routing applications.

How to Draw a Single Turn-by-Turn Direction Step on a Static Map

Casey Rivers — Wed, 04 Feb 2026 12:36:36 +0000

This is the third tutorial in our series on building printable route directions. The full example is available on GitHub:

👉 Printable route directions example

In the previous tutorials, we covered how to request a route and extract turn-by-turn directions and generate a route overview image. Now we tackle a more detailed challenge: creating individual step preview images for each navigation maneuver.

When we built the printable directions demo, we wanted each turn instruction to include a small map showing the context: where the driver is coming from, where they're heading, and exactly where to turn. Text instructions like "Turn right onto Oxford Street" are clearer when paired with a visual that shows the intersection from the driver's perspective.

In this tutorial, you will learn how to extract the right coordinates from a route and render them as oriented, color-coded step previews using the Static Maps API.

Try the live demo:

➡️ View on CodePen

APIs used:

Routing API - get step data and coordinates
Static Maps API - render step preview images

What you will learn:

Extract coordinates for a single step from the route
Draw past/next route segments in different colors
Add a direction arrow for the maneuver
Orient the map using bearing and pitch

Why Step Preview Images?
Extract Step Coordinates
Build Geometry Layers
Calculate Map Bearing
Generate the Image URL
Explore the Demo
Summary
FAQ

Step 1: Why Step Preview Images?

Turn-by-turn directions are clearer with visual context. When we tested the printable directions with real users, we found that text instructions alone often left people uncertain, especially at complex intersections or when multiple turns happen in quick succession.

For each maneuver (turn, merge, roundabout), a small map image shows:

Element	Purpose
Past route (gray)	Where you came from
Next route (pink)	Where you are going
Maneuver line (white/black)	The turn itself
Map orientation	Rotated so "up" is your heading

This is especially useful for:

Printed directions that need to be self-explanatory
PDF route sheets for delivery drivers
Turn-by-turn instruction cards
Any scenario where users can't interact with a live map

💡 Design insight

The color coding is intentional: gray for "past" (already traveled) and a bright color for "next" (where you're going) creates an intuitive visual language. Users understand it without explanation.

Step 2: Understand the Step Data

When you get a route from the Routing API, each step looks like this:

{
  from_index: 6338,
  to_index: 6405,
  instruction: {
    text: "Turn right onto Unter den Linden/B 2/B 5."
  },
  distance: 1389,
  time: 102.587
}

The from_index tells you where this step starts in the route's coordinate array. The route geometry contains all the coordinates:

routeData.geometry.coordinates[0] = [
  [11.582, 48.135],  // index 0
  [11.583, 48.136],  // index 1
  ...
  [13.404, 52.520]   // index 6405 (last point)
]

To create a step preview, we need to extract three segments:

// For a route with 2 waypoints (Munich to Berlin), there's only one leg (index 0)
const coordinates = routeData.geometry.coordinates[0];
const turnCoordinate = coordinates[step.from_index];

// Extract coordinate segments around the turn
const past = getRelatedCoordinates(coordinates, step, 'past');    // Where you came from
const next = getRelatedCoordinates(coordinates, step, 'next');    // Where you're going
const maneuver = getRelatedCoordinates(coordinates, step, 'manoeuvre');  // The turn itself

Each segment is a series of coordinates formatted as a comma-separated string for the Static Maps API.

ℹ️ Index handling for multi-leg routes

The example above assumes a single-leg route (one origin to one destination). For routes with multiple waypoints, you'll need to track which leg you're in and adjust the coordinate array accordingly. The from_index values are relative to each leg's geometry, not the entire route.

Step 3: Draw Colored Route Segments

Now we create the visual layers to draw on the static map. Each segment gets a different color:

const geometries = [];

// Gray line - where you came from
geometries.push(`polyline:${past};linewidth:5;linecolor:${encodeURIComponent('#ad9aad')}`);

// Pink line - where you're going
geometries.push(`polyline:${next};linewidth:5;linecolor:${encodeURIComponent('#eb44ea')}`);

// White line with black border - the turn maneuver
geometries.push(`polyline:${maneuver};linewidth:7;linecolor:${encodeURIComponent('#333333')}`);
geometries.push(`polyline:${maneuver};linewidth:5;linecolor:${encodeURIComponent('#ffffff')}`);

// White arrow - shows direction
geometries.push(`polygon:${maneuverArrow};fillcolor:${encodeURIComponent('#ffffff')}`);

The Static Maps API will draw these layers on top of each other, creating the final image with:

Gray past route - shows where you came from
Pink next route - shows where you're heading
White bordered maneuver - highlights the turn
Direction arrow - points which way to go

Different colored segments help users quickly understand the navigation context.

💡 Layer order matters

The Static Maps API draws layers in the order you specify them. We draw the past route first, then the next route, then the maneuver line on top. This ensures the turn itself is always visible, even if routes overlap.

Step 4: Orient the Map

For a good navigation view, the map should be rotated so "forward" is pointing up. This is how navigation apps work: you're always looking in the direction you're traveling, not at a north-oriented map.

We calculate which direction you're traveling at this turn:

// Calculate bearing (add 180 to rotate map so we're looking forward)
const bearing = calculateBearing(coordinates, step.from_index) + 180;

The bearing is the compass direction (0-360°) you're heading. Adding 180° rotates the map so you're always looking "forward" from the driver's perspective.

💡 Why add 180°?

The bearing tells us which direction the driver is facing. But the Static Maps API's bearing parameter rotates the map itself. If the driver is heading east (bearing 90°), we want east to point up on the map. Adding 180° achieves this rotation.

Step 5: Create the Static Map Image

Finally, build the URL with all the pieces:

const markerCoordinates = `${turnCoordinate[0]},${turnCoordinate[1]}`;

const imageUrl = `https://maps.geoapify.com/v1/staticmap?` +
  `style=osm-bright` +
  `&width=300&height=200` +
  `&center=lonlat:${markerCoordinates}` +
  `&zoom=16` +
  `&bearing=${bearing}` +
  `&pitch=45` +
  `&geometry=${geometries.join('|')}` +
  `&apiKey=${apiKey}`;

This URL creates a 300x200 pixel image:

Centered on the turn coordinate
Rotated to match the direction of travel
Tilted at 45° for a 3D effect
With all the colored route segments overlaid

Key parameters

Parameter	Description
`geometry`	Pipe-separated polyline layers
`center`	Turn coordinate (map center)
`bearing`	Map rotation angle (0-360°)
`pitch`	Tilt angle (0-60°) for 3D effect
`zoom`	Street-level view (typically 15-17)

The pitch=45 gives a slight 3D tilt, making the step preview more visually engaging.

The pitch parameter adds depth to the map, making turns easier to understand.

ℹ️ Choosing the right zoom level

Zoom 16 works well for urban areas where streets are close together. For highway exits or rural roads, you might want zoom 14-15 to show more context. The right zoom depends on your use case, so experiment with different values.

Step 6: Explore the Demo

The live CodePen demo lets you:

Load a route from Munich to Berlin
Select any step from a dropdown
See the step preview image
View the URL breakdown

Experiment with the code

Open the demo in CodePen and try modifying the JavaScript:

Change pitch from 0 to 60 to see the 3D effect
Adjust zoom between 14-18 for different detail levels
Change colors for past/next/maneuver segments
Try different map styles (dark-matter, positron)

Summary

Creating step preview images requires more work than a simple route overview, but the result is significantly more useful for printed directions. The key techniques are:

Extract step coordinates from the route geometry using index values
Build layered geometries showing past, next, and maneuver segments with distinct colors
Calculate bearing to orient the map in the direction of travel
Generate step preview URLs with the Static Maps API, including pitch for depth

These images can be generated on-demand or pre-rendered and cached for frequently used routes. In the next tutorial, we'll add elevation profiles to give users insight into the terrain along their route.

Useful links:

FAQ

Q: Why use different colors for past and next routes?

A: Color coding provides instant visual context. Users can quickly see "where I was" (gray) vs "where I am going" (pink) without reading the instruction text.

Q: What is the bearing parameter?

A: Bearing rotates the map so that "up" matches the direction of travel. A bearing of 0° points north, 90° points east, 180° points south, and 270° points west.

Q: Can I add custom icons or text to the step preview?

A: Yes. Use the marker parameter to add icons with custom colors, sizes, and text. See the Map Marker Icon API for options.

Q: What is the pitch parameter?

A: Pitch tilts the map from 0° (flat, top-down) to 60° (maximum tilt). A pitch of 45° gives a slight 3D perspective that makes navigation clearer.

Q: How do I handle roundabouts or complex intersections?

A: For roundabouts, extract more coordinates in the maneuver segment (e.g., -10 to +20 instead of -5 to +10) to show the circular path. The bearing calculation will orient the map correctly.

Q: Can I generate these images server-side?

A: Yes. The Static Maps API works from any HTTP client. Generate the URLs server-side and either serve the images directly or cache them for faster delivery.

Q: Why use two polylines for the maneuver (black + white)?

A: Layering a thinner white line over a thicker black line creates a bordered effect that stands out against both light and dark backgrounds, making the turn more visible.

What's Next?

This tutorial covered individual step preview images. In the next part of the series, we'll add elevation profiles: charts that show the terrain along the route, useful for hiking, cycling, and understanding the difficulty of a journey.

👉 Part 4: Create a Route Elevation Profile with Chart.js

Try It Now

👉 Open the Live Demo

Please sign up at geoapify.com and generate your own API key to start creating printable turn-by-turn directions.