DEV Community: Geoapify Maps API

What Is Route Optimization? Algorithms, APIs, and Open-Source Tools

Alfiya Tarasenko — Fri, 05 Jun 2026 12:42:37 +0000

Whether you’re building a delivery platform, a field service application, or a logistics solution, you’ll eventually face the same challenge: finding the best route for multiple stops.

At first glance, the problem seems straightforward. Just visit all stops while minimizing travel time or distance.

In reality, route optimization quickly becomes complex. Even a route with 10 stops can have millions of possible combinations, and real-world constraints such as delivery time windows, vehicle capacities, driver schedules, and pickup-and-delivery requirements make the problem even harder.

In this article, we'll cover:

What route optimization is
How route optimization problems are modeled with VRP
Algorithms used to solve route optimization problems
Ready-to-use route optimization applications
Route Optimization APIs
Open-source route optimization tools
How to choose the right solution

What Is Route Optimization?

Route optimization is the process of finding the most efficient routes for one or more vehicles while satisfying a set of constraints.

The goal is typically to minimize travel time, distance, or operational costs while ensuring that all required stops are visited.

Unlike simple routing, route optimization is not just about finding the shortest path between two points. It must also determine the order in which stops should be visited, assign stops to vehicles, and satisfy various operational constraints.

Routing focuses on finding a path between locations. Route optimization focuses on finding the best set of routes while satisfying real-world constraints.

Common constraints include:

Vehicle capacities
Delivery time windows
Driver schedules
Pickup and delivery requirements

As the number of stops and constraints grows, route optimization becomes increasingly difficult to solve.

Modeling Route Optimization with VRP

As route optimization problems become larger and more complex, they require a formal way to represent vehicles, stops, objectives, and constraints.

In operations research and computer science, these challenges are commonly modeled as the Vehicle Routing Problem (VRP).

Over the years, numerous VRP variants have been developed to represent different real-world requirements:

Problem Type	Description	Common Constraints
Vehicle Routing Problem (VRP)	The basic problem of assigning locations to vehicles and determining the best visit order.	Travel time, distance, cost
Capacitated Vehicle Routing Problem (CVRP)	Vehicles have limited capacity, such as weight, volume, or number of packages.	Vehicle capacity, load balancing
Vehicle Routing Problem with Time Windows (VRPTW)	Deliveries or visits must occur within specified time windows.	Delivery windows, service duration, driver schedules
Pickup and Delivery Problem (PDP)	Items must be picked up at one location and delivered to another.	Pickup-before-delivery, vehicle capacity
Multi-Depot Vehicle Routing Problem (MDVRP)	Vehicles can start and end at different depots.	Depot assignment, vehicle availability
Open Vehicle Routing Problem (OVRP)	Vehicles do not need to return to their starting depot.	End location flexibility
Periodic Vehicle Routing Problem (PVRP)	Customers require visits on specific days according to a schedule.	Visit frequency, planning horizon
Dynamic Vehicle Routing Problem (DVRP)	New jobs or changes can occur while routes are already in progress.	Real-time updates, traffic, new orders

Most real-world route optimization systems combine several of these variants. For example, a delivery application may need to handle vehicle capacities, customer time windows, multiple depots, pickup-and-delivery operations, driver shifts, breaks, and priority deliveries simultaneously.

How Route Optimization Is Solved

Route optimization belongs to a class of computationally difficult problems. As the number of stops increases, the number of possible route combinations grows exponentially, making it impractical to evaluate every possible solution.

For example:

5 stops → 120 possible routes
10 stops → 3.6 million possible routes
20 stops → over 2 quintillion possible routes

And that's before considering multiple vehicles, time windows, capacities, or other constraints.

Because of this, route optimization systems rely on specialized algorithms that search for high-quality solutions without evaluating every possible route.

Exact Algorithms

Exact algorithms guarantee the optimal solution. Common approaches include:

Algorithm	Description	Best For
Branch and Bound	Systematically explores possible solutions while pruning suboptimal branches.	Small to medium-sized optimization problems
Mixed Integer Programming (MIP)	Models route optimization using variables, objectives, and constraints solved mathematically.	Complex optimization problems with many business constraints

These methods systematically explore the solution space while using mathematical techniques to eliminate suboptimal solutions.

While highly accurate, exact algorithms become computationally expensive as the number of stops, vehicles, and constraints grows. As a result, they are typically used for smaller optimization problems or as benchmarks for evaluating other approaches.

Heuristics and Metaheuristics

Most modern route optimization systems rely on heuristics and metaheuristics that can find high-quality solutions much faster than exact algorithms.

Common approaches include:

Algorithm	Description	Best For
Clarke-Wright Savings Algorithm	A classic heuristic that builds routes by merging stops in a way that maximizes travel savings.	Quickly generating initial solutions for routing problems
Local Search	Starts with an existing solution and iteratively improves it by making small changes.	Refining and improving existing routes
Tabu Search	An advanced local search technique that avoids revisiting recently explored solutions.	Large optimization problems with many local optima
Simulated Annealing	Occasionally accepts worse solutions to escape local optima and explore more of the search space.	Complex optimization problems where local search may get stuck
Genetic Algorithms	Inspired by biological evolution, combining and mutating solutions over multiple generations.	Large-scale optimization problems with many constraints

Rather than evaluating every possible route, these methods intelligently explore the search space and iteratively improve solutions.

While they do not guarantee the mathematically optimal result, they can often find near-optimal solutions in seconds, making them well suited for large-scale route optimization problems involving hundreds or thousands of stops.

In practice, many route optimization systems combine multiple techniques. For example, a solver may generate an initial route using a heuristic and then improve it using local search or other metaheuristic methods.

Route Optimization Solutions

Fortunately, you don't need to implement route optimization algorithms from scratch. A wide range of solutions already exists, from business applications designed for non-technical users to open-source solvers and Route Optimization APIs that can be integrated directly into your applications.

Ready-to-Use Applications

Ready-to-use route optimization applications provide a complete solution for planning and managing routes. They typically include route optimization, driver management, dispatching, tracking, and reporting features through a web interface, allowing businesses to start optimizing routes without writing any code.

Product	Description	Best For
OptimoRoute	Route planning and field service management platform with route optimization, scheduling, and tracking capabilities.	Delivery businesses and field service teams
Onfleet	Last-mile delivery management platform focused on dispatching, driver tracking, and route optimization.	Delivery and logistics companies
Routific	Cloud-based route optimization software designed for delivery operations.	Small and medium-sized delivery fleets
Circuit for Teams	Route planning platform with driver apps, dispatch tools, and route optimization.	Local delivery businesses
RouteXL	Online route optimization tool that helps plan multi-stop routes through a simple web interface.	Small businesses and occasional route planning
MyRouteOnline	Route planning software that optimizes routes from spreadsheets and address lists.	Businesses managing routes from Excel or CSV files

These platforms are ideal when you need route optimization as a business tool. However, if you're building your own application or need complete control over the optimization process, open-source route optimization engines may be a better fit.

Route Optimization APIs

Route Optimization APIs provide route optimization capabilities through a web service, allowing developers to integrate optimization directly into their applications without managing optimization engines or infrastructure.

Most APIs accept a list of locations, vehicles, and constraints, then return optimized routes, stop assignments, and scheduling information.

API	Description	Best For
Geoapify Route Optimization API	Route optimization API supporting multiple vehicles, capacities, time windows, pickup and delivery operations, and route balancing.	Applications that need route optimization without managing infrastructure
Google Route Optimization API	Enterprise-grade route optimization service built on Google's mapping and routing infrastructure.	Large-scale logistics and enterprise applications
NextBillion.ai Route Optimization API	Optimization API focused on logistics, dispatching, and delivery operations.	Logistics and delivery applications

Advantages

Route Optimization APIs are often the fastest way to add optimization capabilities to an application. They eliminate the need to implement complex algorithms, manage optimization infrastructure, or maintain routing engines.

Key benefits include:

Fast integration
No infrastructure to manage
No solver expertise required
Automatically updated and maintained
Scales with application usage

Challenges

Like any managed service, Route Optimization APIs come with trade-offs. While they significantly reduce development and operational effort, they may not provide the same level of control as self-hosted solutions.

Common considerations include:

Usage-based pricing
Less flexibility than self-hosted solutions
Limited access to underlying optimization logic

Open-Source Route Optimization Tools

For developers who need complete control over the optimization process, open-source route optimization tools provide a flexible alternative to commercial applications and managed APIs.

These tools implement many of the algorithms discussed earlier and can be integrated into custom applications, self-hosted platforms, or research projects.

Tool	Language	Description	Best For
Google OR-Tools	C++, Python, Java, C#	Comprehensive optimization toolkit that includes powerful Vehicle Routing Problem (VRP) solvers and support for many routing constraints.	Custom optimization applications and research
VROOM	C++	High-performance route optimization engine designed specifically for vehicle routing problems. Integrates with routing engines such as OSRM, Valhalla, and Openrouteservice.	Logistics and delivery platforms
jsprit	Java	Java toolkit for solving vehicle routing problems with support for capacities, time windows, and custom constraints.	Java-based route optimization applications

Google's OR-Tools is one of the most widely used open-source optimization frameworks and is frequently used for solving Vehicle Routing Problems.

Advantages

Open-source tools provide maximum flexibility and allow organizations to fully control how route optimization is implemented and deployed.

Key benefits include:

No per-request usage fees
Full control over optimization logic
Ability to customize constraints and objectives
Self-hosted deployment
Access to source code

Challenges

Using open-source solvers typically requires more engineering effort than ready-to-use applications or APIs.

Common considerations include:

Infrastructure and deployment management
Integration with routing engines
Building a distance matrix or travel time matrix for all locations
Solver configuration and tuning
Maintenance and upgrades
Additional development effort

Many route optimization engines, including VROOM and OR-Tools, rely on a travel time or distance matrix that describes the cost of traveling between every pair of locations. Generating this matrix can be computationally expensive and typically requires integration with a routing service.

For example, the Geoapify Route Matrix API can generate travel time and distance matrices that can then be used as input for route optimization engines.

How to Choose the Right Solution

The best route optimization solution depends on how much control and customization you need.

If you want to...	Recommended Solution
Start optimizing routes immediately without development	Ready-to-use application
Give dispatchers and drivers a complete route planning solution	Ready-to-use application
Add route optimization to an existing application	Route Optimization API
Build a custom route optimization workflow	Route Optimization API
Self-host the optimization engine	Open-source tool
Customize optimization logic and constraints	Open-source tool
Experiment with optimization algorithms	Open-source tool
Avoid managing infrastructure and optimization engines	Route Optimization API
Have full control over the optimization process	Open-source tool

In Summary

Choose a ready-to-use application if you want to optimize routes without writing code or managing technical infrastructure.
Choose a Route Optimization API if you're building an application and need route optimization capabilities without implementing optimization algorithms yourself.
Choose an open-source tool if you need maximum flexibility, self-hosting, or complete control over the optimization process.

There is no universally best route optimization solution. The right choice depends on whether your priority is ease of use, rapid integration, or maximum flexibility. Understanding the trade-offs between applications, APIs, and open-source tools will help you choose a solution that matches both your technical requirements and business goals.

How to Geocode Thousands of Addresses for Free

Alfiya Tarasenko — Thu, 04 Jun 2026 09:27:46 +0000

Geocoding large address datasets (finding latitude and longitude coordinates for addresses) can quickly become expensive, especially when you need to process hundreds or thousands of records. This can be a challenge for businesses, researchers, and individuals working with limited budgets.

Fortunately, there are several ways to geocode thousands of addresses completely free of charge, and in this article we’ll explore the most practical options.

How to Geocode Thousands of Addresses for Free

Yes. While most geocoding services charge based on usage, many providers offer free quotas that are large enough for one-time projects, research, testing, and small business needs.

Note: "Free" does not necessarily mean unlimited. Most services apply daily quotas, rate limits, or file-size restrictions. In some cases, free usage may require more effort, such as splitting large datasets into smaller batches, waiting for daily quotas to reset, or processing data over multiple days.

However, with the right approach, these limits are often sufficient to geocode thousands—or even tens of thousands—of addresses without spending money.

The exact limits depend on the approach you choose. Here are three practical ways to geocode thousands of addresses for free:

Method	Free Limit	Best For
Online Tool	2,500 addresses per run	CSV files, no coding
Geocoding API	3,000 addresses/day	Applications and automation
Batch Geocoding API	Up to 6,000 addresses/day (priority 0.5)	Large datasets
Self-Hosted Geocoder	Depends on your infrastructure	Very large datasets

Let's take a closer look at each option and see when it makes the most sense to use it.

Method #1: Use an Online Geocoding Tool

The simplest way to geocode a large address dataset is to use an online geocoding tool. This approach requires no coding, no API integration, and no software installation. You simply upload a CSV or Excel file containing addresses and download the results.

For example, GeoSearch Online allows you to upload CSV and Excel files and geocode up to 2,500 addresses per run for free. The service returns latitude and longitude coordinates along with standardized address information and other useful location data.

Upload a CSV or Excel file containing addresses and geocode up to 2,500 records for free.

How it works

Export your address list to a CSV or Excel file.
Upload the file to GeoSearch Online.
Select the address column to geocode.
Start the geocoding process.
Download the resulting file with coordinates.

Example

The following example shows how a list of addresses can be enriched with coordinates and standardized address data.

Before geocoding:

original_address
1 Apple Park Way, Cupertino, CA
350 5th Ave, New York, NY

After geocoding:

original_address	lat	lon	formatted
1 Apple Park Way, Cupertino, CA	37.3302112	-122.010771	1 Apple Park Way, Cupertino, CA 94087, United States of America
350 5th Ave, New York, NY	40.7484421	-73.9856589	Empire State Building, 350 5th Avenue, New York, NY 10118, United States of America

In addition to latitude and longitude coordinates, geocoding services often return standardized address components such as house numbers, street names, postcodes, cities, states, countries, and confidence scores. This enriched data can help with address validation, data cleaning, analytics, and mapping applications.

Summary

Pros	Cons
• No coding required • Works directly with CSV and Excel files • Fast and easy to use • Suitable for one-time projects	• Requires manual file upload • Large datasets may need to be split into multiple files • Not suitable for automated workflows

Free Limit: Up to 2,500 addresses per run.

Best for: Businesses, researchers, students, and anyone who needs to geocode a spreadsheet without writing code.

Method #2: Use a Geocoding API

If you need to geocode addresses regularly or integrate geocoding into an application, a geocoding API is often a better choice than an online tool. Instead of uploading files manually, your application sends addresses directly to the API and receives the results programmatically.

Unlike online tools that process an entire file at once, geocoding APIs typically work synchronously. Your application sends an address, waits for the response, and immediately receives latitude, longitude, and standardized address information. This makes APIs a great choice for websites, mobile apps, internal tools, and automated workflows that require real-time geocoding.

For example, the Geoapify Geocoding API provides up to 3,000 free requests per day.

How it works

Create a free account at Geoapify and obtain an API key.
Send an address and your API key to the geocoding API.
The API searches for the best matching location.
Receive latitude, longitude, and additional address details in the response.
Store or use the results in your application.

Example: Geocode a Single Address

const apiKey = "YOUR_API_KEY";

const address = "1 Apple Park Way, Cupertino, CA";

fetch(
  `https://api.geoapify.com/v1/geocode/search?text=${encodeURIComponent(address)}&apiKey=${apiKey}`
)
  .then(response => response.json())
  .then(result => {
    console.log(result.features[0].properties);
  });

The response contains coordinates, a formatted address, and additional location details that can be used for mapping, analytics, and address validation.

Respecting Rate Limits

Since each address requires a separate API request, it’s important to respect the API’s rate limits.

For example, the Geoapify free plan allows up to 5 requests per second and 3,000 requests per day. A rate-limiting library can help automatically distribute requests over time.

Example: Using a Rate Limiter

The @geoapify/request-rate-limiter package helps distribute requests according to your plan limits.

const RequestRateLimiter = require('@geoapify/request-rate-limiter');

const apiKey = 'YOUR_API_KEY';

// Function that geocodes a single address
async function geocodeAddress(address) {
    const response = await fetch(
        `https://api.geoapify.com/v1/geocode/search?text=${encodeURIComponent(address)}&apiKey=${apiKey}`
    );

    return await response.json();
}

// List of addresses to geocode
const addresses = [
    "1 Apple Park Way, Cupertino, CA",
    "350 5th Ave, New York, NY",
    "1600 Amphitheatre Parkway, Mountain View, CA"
];

// Convert each address into a request function
const requests = addresses.map(address => {
    return () => geocodeAddress(address);
});

// Process requests while respecting rate limits
RequestRateLimiter.rateLimitedRequests(
    requests,
    5,      // Maximum requests per interval
    1000    // Interval duration in milliseconds
)
.then(results => {
    console.log('All addresses processed');
    console.log(results);
})
.catch(error => {
    console.error('Error processing requests:', error);
});

Summary

Pros	Cons
• Easy to automate • Integrates directly into applications and scripts • Returns results immediately • No manual file uploads	• Requires programming knowledge • Daily usage limits apply • Requests must respect rate limits • Large datasets may take time to process

Free limit: Up to 3,000 requests per day.

Best for: Applications, websites, scripts, and automated workflows that need real-time geocoding.

Method #3: Use a Batch Geocoding API

If you need to geocode thousands of addresses at once, a batch geocoding API can be more efficient than sending individual requests through a standard geocoding API.

Unlike synchronous APIs that process one address per request and return results immediately, batch geocoding APIs work asynchronously. You submit a large set of addresses as a job, wait for the processing to complete, and then download the results. This approach is designed specifically for large datasets and avoids the need to manage thousands of individual requests.

For example, the Geoapify Batch Geocoding API allows you to submit up to 1,000 addresses per job. If your dataset is larger, you can simply submit multiple batch jobs and process them independently.

An additional advantage of batch geocoding is the priority parameter. Lower-priority jobs cost fewer credits because they are processed when system resources are available. For example, using a priority=0.5 reduces the processing cost by 50%. As a result, the free plan’s daily quota can process up to 6,000 addresses per day instead of 3,000.

How it works

Create a free account at Geoapify and obtain an API key.
Prepare a list of addresses to geocode.
Submit the addresses as a batch job.
Wait for the job to complete.
Download the results containing coordinates and standardized address information.

Example: Batch Geocoding with a Library

While you can work directly with the Batch Geocoding API, using the @geoapify/batch-geocoding library simplifies the asynchronous workflow by handling job creation, polling, and result retrieval.

import { Batcher } from "@geoapify/batch-geocoding";

// Create SDK client with your API key
const batcher = new Batcher("YOUR_API_KEY");

// Submit a batch geocoding job
const job = batcher.geocode(
  [
    {
      text: "1000 5th Ave, New York, NY 10028, United States"
    },
    {
      text: "11 W 53rd St, New York, NY 10019, United States"
    },
    /* Up to 1,000 addresses can be submitted in a single batch job*/
  ],
  {
    priority: 0.5 // Lower-priority processing
  }
);

// Wait for processing to complete and retrieve results
const jsonResult = await job.getResults().then(result => result.json());

console.log(jsonResult);

The library submits the batch job, waits for processing to complete, and returns the geocoding results, making it much easier to work with large datasets.

Summary

Pros	Cons
• Designed for large datasets • Processes many addresses in a single job • Higher free throughput than synchronous APIs • Supports discounted low-priority processing	• Results are not immediate • Requires programming knowledge • Jobs may take time to complete • Not suitable for real-time geocoding

Free limit: Up to 3,000 addresses per day, or up to 6,000 addresses per day when using priority=0.5.

Best for: Large address datasets, data enrichment projects, migrations, and bulk geocoding workflows.

Method #4: Use a Self-Hosted Geocoding Engine

If you need complete control over your geocoding infrastructure or want to process very large datasets without API quotas, you can run an open-source geocoding engine on your own server.

Unlike hosted geocoding services, self-hosted solutions require you to install, configure, and maintain the software, as well as regularly update the underlying geographic data. In return, you are not limited by API quotas and can process as many addresses as your hardware can handle.

Several mature open-source geocoding engines are available:

Engine	Description	Documentation	Installation
Nominatim	The most widely used OpenStreetMap geocoder	Docs	Install
Pelias	A highly scalable geocoder built for large deployments	Docs	Install
Photon	A lightweight geocoder based on OpenStreetMap data and Elasticsearch	Docs	Install

While self-hosting removes usage limits, it introduces infrastructure costs and operational complexity. Importing and indexing OpenStreetMap data can require significant disk space, memory, and processing time, depending on the geographic area covered.

Summary

Pros	Cons
• No API quotas • Full control over data and infrastructure • Suitable for very large datasets • Can be integrated into internal systems	• Requires server infrastructure • Installation and maintenance effort • Data updates must be managed manually • Results may vary depending on data quality and configuration • Higher technical complexity

Free limit: No API quotas. Limited only by your infrastructure.

Best for: Organizations processing large volumes of addresses, companies with strict data requirements, and teams that need full control over their geocoding infrastructure.

Which Method Should You Choose?

The best option depends on your dataset size, technical skills, and automation requirements.

Method	Free Limit	Coding Required	Best For
Online Tool	2,500 addresses per run	No	One-time CSV or Excel processing
Geocoding API	3,000 addresses per day	Yes	Applications and automation
Batch Geocoding API	Up to 6,000 addresses per day (priority 0.5)	Yes	Large datasets
Self-Hosted Geocoder	Depends on infrastructure	Yes	Very large datasets and full control

Choose an online geocoding tool if you have a spreadsheet and need a quick, no-code solution.
Choose a geocoding API if you need real-time geocoding in an application, website, or automated workflow.
Choose a batch geocoding API if you need to process thousands of addresses efficiently and don't need immediate results.
Choose a self-hosted geocoding engine if you need full control over your infrastructure and are prepared to manage the software and data yourself.

For most users, an online tool is the easiest place to start. If you need automation, APIs provide more flexibility, while batch processing and self-hosted solutions are better suited for large-scale geocoding projects.

Conclusion

Geocoding thousands of addresses for free is entirely possible. Whether you prefer a simple online tool, a geocoding API, a batch processing service, or a self-hosted solution, the best choice depends on your dataset size, automation requirements, and technical expertise.

For most users, an online tool is the easiest option, while APIs and batch processing provide more flexibility for larger and recurring geocoding tasks.

Related Resources

What Is the Difference Between a Routing API and a Route Optimization API?

Alfiya Tarasenko — Mon, 20 Apr 2026 12:11:30 +0000

If you're building a map-based or logistics application, you’ll likely come across two terms that sound very similar: Routing API and Route Optimization API.

At first glance, they may seem interchangeable. Both deal with routes, distances, and travel time. But in practice, they solve very different problems.

In simple terms

A routing API calculates the path between given points and returns the actual route (geometry, distance, time)
A route optimization API determines the most efficient order of stops, without necessarily returning full route geometry

For example, a routing service like the Geoapify Routing API helps you build directions from point A to point B, from B to C, and so on — following a predefined order.

In contrast, the Geoapify Route Optimization API is designed to organize multiple stops — even across multiple vehicles — into the most efficient routes.

In this article, we’ll break down the difference step by step, compare how each API works, and show when to use one over the other.

What is a Routing API?

A routing API is used to calculate the path between locations in a predefined order.

You provide a list of waypoints, and the API returns the route that connects them — including distance, estimated travel time, and often turn-by-turn instructions.

Key characteristics

Works with a fixed sequence of points (A → B → C)
Returns full route geometry (coordinates for map display)
Provides distance and travel time
Can include turn-by-turn navigation instructions
Supports different travel modes (driving, walking, cycling, etc.)
Allows avoiding specific route parts (tolls, highways, ferries, etc.)
Can provide additional details like road type, surface, and other route attributes

Example use cases

Showing directions from a user’s location to a destination
Displaying a route on a map
Building navigation features in apps

Try it yourself

You can test routing requests in the. Geoapify API Playground: enter a few waypoints and see how the API builds a route step by step.

What is a Route Optimization API?

A route optimization API is designed to find the most efficient way to visit multiple locations.

Instead of following a predefined order, you provide a list of stops, and the API determines the best sequence to minimize travel time, distance, or overall cost.

Key characteristics

Works with an unordered set of locations
Optimizes the sequence of stops
Supports multiple vehicles and route assignments
Focuses on efficiency (time, distance, cost)
Can handle constraints like time windows, capacities, or working hours
Does not necessarily return full route geometry (focus is on planning)

Example use cases

Delivery route planning
Field service scheduling
Logistics and fleet management
Last-mile delivery optimization

Try it yourself

You can experiment with route optimization in the Geoapify API Playground: generate a task, visualize it on the map, solve it, and check the optimized result.

Routing API vs Route Optimization API

The difference between these two APIs is easiest to understand when viewed side by side:

Feature	Routing API	Route Optimization API
Main goal	Calculate a route between points	Find the most efficient order of stops
Input	Ordered waypoints (A → B → C)	Unordered locations (optionally with multiple vehicles)
Output	Route geometry, distance, time	Optimized sequence + route assignments
Focus	Navigation	Planning & efficiency
Usage	Route planning and live navigation	Route planning
Multi-vehicle support	❌ No	✅ Yes
Constraints (time windows, capacity, shifts)	❌ No	✅ Yes

Key takeaway

Routing API → connects points in a given order
Route Optimization API → determines the best order of points

In short: routing builds routes, optimization plans them.

When to Use Each API

Choosing between a Routing API and a Route Optimization API depends on the problem you’re solving.

Use a Routing API if:

You need directions between points
The order of stops is already known
You want to display routes on a map
You are building navigation features (including live navigation)

Example:

Show directions from a user’s location to a destination, or follow a predefined route A → B → C.

Use a Route Optimization API if:

You have multiple stops and the order is not fixed
You want to minimize travel time, distance, or cost
You need to plan routes for multiple vehicles
You have constraints like time windows or capacity

Example:

Plan delivery routes for 20 addresses across several drivers.

Use both together (common in real apps)

In many applications, these APIs are combined:

Route Optimization API → determines the best order of stops
Routing API → builds the actual routes between those stops

In practice, you often need to use a Routing API after optimization to generate routes between the optimized waypoints, visualize them on a map, or provide navigation instructions.

This approach gives you both efficiency and detailed route information.

Conclusion

Routing APIs and Route Optimization APIs may sound similar, but they solve fundamentally different problems.

Routing API → calculates how to get from one point to another
Route Optimization API → decides the best order to visit multiple points

If your app needs directions or navigation, a Routing API is the right choice.

If you’re planning deliveries, field service routes, or logistics workflows, you’ll need a Route Optimization API.

In many real-world applications, the best solution is to use both:

Optimization to plan the route
Routing to build and display it

Understanding this difference helps you choose the right tool, avoid unnecessary complexity, and build more efficient applications.

Try it yourself

Want to see the difference in action?

Routing API → https://apidocs.geoapify.com/playground/routing/
Route Optimization API → https://apidocs.geoapify.com/playground/route-planner/

Create a simple route and then try optimizing multiple stops — the difference becomes immediately clear.

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: