Forem: Alfiya Tarasenko

Got coordinates but need a city or ZIP code? This guide shows how to convert lat/lon into address data using reverse geocoding — with real examples, API calls, and a live demo.

Alfiya Tarasenko — Tue, 31 Mar 2026 11:47:09 +0000

Alfiya Tarasenko for Geoapify Maps API

Mar 31

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

#webdev #codenewbie #programming #javascript

Comments

7 min read

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.

Loading hundreds of places on a map? Learn how to make it fast and smooth! This tutorial shows how to use the Geoapify Places API with Leaflet, split map areas into chunks, and apply rate limiting for better performance and UX.

Alfiya Tarasenko — Fri, 07 Nov 2025 14:19:03 +0000

Alfiya Tarasenko for Geoapify Maps API

Nov 7 '25

Handle Large Place Searches: Chunked and Rate-Limited Search in Leaflet

#webdev #leaflet #api #javascript

Comments

6 min read

Handle Large Place Searches: Chunked and Rate-Limited Search in Leaflet

Alfiya Tarasenko — Fri, 07 Nov 2025 14:18:23 +0000

In the previous tutorial, we used the Geoapify Places API and Leaflet to display nearby places — like parks, museums, and cinemas — on a map.

That simple approach works well for small areas, but loading hundreds of places at once can slow the map or exceed API rate limits.

In this part, you’ll learn how to make place searches more efficient by:

Splitting the map area into chunks for smaller, faster requests
Applying rate limiting to control request flow
Rendering results progressively for smoother UX

Try the full example:
➡️ View on CodePen

Sure! Here’s a clean, Dev.to–ready Table of Contents for your article.
It matches your section headings exactly and uses the same anchor style Dev.to automatically generates.

🧭 Table of Contents

Introduction
Why large place searches can be slow
A better approach
Split the map bounds into smaller fragments
Run fragment requests with rate limiting
See the full implementation
Summary

Why large place searches can be slow

When your map covers a large area — for example, an entire city — the Geoapify Places API may need to process thousands of locations at once.
If you request all of them in a single query:

The API call can take longer to complete.
The response size becomes large, increasing data transfer time.
The map may freeze while parsing or rendering the results.
Users experience visible lag or delayed updates.
It might even require querying multiple pages of results to retrieve all places in that area.

A better approach

To keep your app fast and user-friendly, it’s better to:

Split the map area into smaller parts (chunks)

Each chunk is a smaller rectangle inside the visible map bounds.
The app sends several lightweight queries instead of one large request.
Results load progressively — users start seeing places immediately while others continue loading in the background.

Description: A map view divided into several rectangles, each labeled “API request,” showing places being loaded one fragment at a time. Arrows can indicate parallel or sequential loading.

Apply rate limiting

When you send multiple requests in parallel — for example, one per map fragment — it’s important to control how often they are executed.

Without rate limiting, dozens of simultaneous API calls can overload the network or exceed the API’s allowed request rate, leading to HTTP 429 (Too Many Requests) errors.

The Geoapify Request Rate Limiter automatically spaces out requests over time.
It ensures you stay within the API’s limits, keeps the map responsive, and provides a smooth, continuous loading experience for users.

Description: If rate limits are not respected, some API requests return 429 (Too Many Requests) errors.
In this example, the API allows 5 requests per second, but 9 are sent simultaneously — so 4 fail. The map shows those failed fragments highlighted in red.

Now that we understand why large queries can cause slow responses or 429 errors, let’s look at how to split the visible map area into smaller fragments.

Split the map bounds into smaller fragments

To make large-area searches more efficient, we’ll divide the visible map area into several smaller rectangles, called fragments.

For example, the following helper function decides how many pieces the map should be split into depending on the zoom level (fewer at high zoom, more at low zoom):

function getAxisChunksForZoom(zoom) {
  const z = Math.floor(zoom);
  const delta = Math.max(0, 17 - z);
  if (delta === 0) return 1;        // At zoom ≥ 16, one request is enough
  return delta;   // At lower zooms, split the area into more parts
}

The function takes the current map zoom level as input.
When you’re zoomed in close (zoom ≥ 16), the visible area is small, so only one fragment (one request) is needed.
As you zoom out, the visible area grows. The function increases the number of fragments exponentially — for example:
- At zoom 15 → 2 x 2 fragments per axis
- At zoom 14 → 3 x 3 fragments
- At zoom 13 → 4 x 4 fragments
This ensures that large views (like an entire city) are split into multiple smaller bounding boxes, each of which can be queried quickly and displayed independently.

Next, we’ll use this helper to actually divide the map bounds into fragments — small rectangular areas that together cover the visible region.

The following function, getFragments(bounds, zoom), takes the current map bounds and zoom level, then returns an array of rectangles. Each rectangle defines a mini viewbox that we’ll later use to query the Geoapify Places API:

function getFragments(bounds, zoom) {
  if (!bounds) return [];

  const chunks = getAxisChunksForZoom(zoom);
  const sw = bounds.getSouthWest();
  const ne = bounds.getNorthEast();

  // If only one chunk, return the full map bounds
  if (chunks <= 1) {
    return [{ minLng: sw.lng, minLat: sw.lat, maxLng: ne.lng, maxLat: ne.lat }];
  }

  const latStep = (ne.lat - sw.lat) / chunks;
  const lngStep = (ne.lng - sw.lng) / chunks;
  const rects = [];

  // Loop through rows and columns to build smaller rectangles
  for (let row = 0; row < chunks; row += 1) {
    const minLat = sw.lat + row * latStep;
    const maxLat = row === chunks - 1 ? ne.lat : minLat + latStep;

    for (let col = 0; col < chunks; col += 1) {
      const minLng = sw.lng + col * lngStep;
      const maxLng = col === chunks - 1 ? ne.lng : minLng + lngStep;
      rects.push({ minLng, minLat, maxLng, maxLat });
    }
  }

  return rects;
}

What this does

Calculates how many pieces (chunks) the area should be split into based on zoom level.
Divides the visible map into a grid of rectangles, using latitude and longitude steps.
Returns an array of bounding boxes — each one ready to be used in a request like:

  filter=rect:minLon,minLat,maxLon,maxLat

As a result, instead of sending one large, heavy API query, we can make multiple smaller requests — one per fragment — and load results progressively and smoothly.

Run fragment requests with rate limiting

Now that we can split the view into fragments and build one request per fragment, let’s execute them safely.
We’ll use [@geoapify/request-rate-limiter](https://www.npmjs.com/package/@geoapify/request-rate-limiter) to pace requests so the UI stays smooth and we avoid bursts.

// Build one async function per fragment (from previous step)
const requestFns = fragments.map(({ minLng, minLat, maxLng, maxLat }) => {
  const rect = `${minLng},${minLat},${maxLng},${maxLat}`;
  const url = `https://api.geoapify.com/v2/places?categories=${encodeURIComponent(categories)}&filter=rect:${rect}&limit=200&apiKey=${yourAPIKey}`;

  return async () => {
    const resp = await fetch(url);
    if (!resp.ok) throw new Error(`HTTP ${resp.status}`);
    const data = await resp.json();
    renderResults(data); // progressive rendering: draw as each fragment returns
    return data;
  };
});

// Run with rate limiting: 5 requests per 1000 ms window
const results = await RequestRateLimiter.rateLimitedRequests(
  requestFns,
  5,          // max requests per window
  1000,       // window duration (ms)
  {
    onProgress: ({ completedRequests, totalRequests }) => {
      // optional: update a small status label
      // e.g., setStatus(`Loaded ${completedRequests}/${totalRequests} fragments…`);
    }
  }
);

Paces outgoing requests to avoid spikes and keep the app responsive.
Renders progressively: users see places appear fragment-by-fragment, not all at once.
Keeps your code simple: pass an array of tasks and let the limiter schedule them.

See the full implementation

You can explore the complete working version in the CodePen example:
➡️ View on CodePen

The code sample demonstrates everything described in this tutorial — including:

Rate-limited API requests to keep the app smooth and avoid 429 errors
Canceling outdated searches when the user moves or zooms the map again
Progressive visualization of results as each fragment loads

Together, these techniques make large place searches fast, stable, and user-friendly — even when displaying thousands of points across a wide area.

Summary

In this tutorial, we improved the performance of large-area searches in Leaflet using the Geoapify Places API.

You learned how to:

Split the visible map area into smaller fragments for faster, lighter API calls
Apply rate limiting with the Geoapify Request Rate Limiter to avoid 429 errors
Load and render places progressively for a smoother, more responsive user experience

You can see the complete implementation — including canceling outdated searches and visualizing data — in the live CodePen example:
➡️ View the complete example

[Boost]

Alfiya Tarasenko — Wed, 05 Nov 2025 14:31:05 +0000

How to Query and Display Nearby Places on a Leaflet Map with the Geoapify Places API

Alfiya Tarasenko for Geoapify Maps API ・ Nov 5

#codepen #leaflet #webdev #geoapify

How to Query and Display Nearby Places on a Leaflet Map with the Geoapify Places API

Alfiya Tarasenko — Wed, 05 Nov 2025 13:46:21 +0000

In this tutorial, you’ll learn how to use the Geoapify Places API with Leaflet to display nearby places — such as parks, museums, and cinemas — on an interactive map.

Try the live example:
➡️ View on CodePen

In this part, we’ll focus on the basics:

Querying the Places API by category
Parsing and displaying GeoJSON results
Styling map markers with the Geoapify Marker Icon API and showing popups in Leaflet

🧭 Table of Contents

Step 1 – Set up the Leaflet Map
Step 2 – Query Places by Category Using the Geoapify Places API
Step 3 – Display Places as Custom Markers (Marker Icon API)
Summary

Step 1 – Set up the Leaflet Map

Let’s start by setting up a basic Leaflet map with Geoapify basemap tiles.

Tip: You don’t need to build it from scratch — use this ready-to-edit CodePen template:
➡️ Open Leaflet Map Template
It will create a new Codepen with a Leaflet map. Please replace the template Geoapify API key with your API key. Register and get your Free API key here.

Here are main steps to create a map:

const yourAPIKey = "YOUR_GEOAPIFY_API_KEY";

// Create the map and center it on London
const map = L.map("map").setView([51.5074, -0.1278], 14);

// Detect high-resolution displays for crisper tiles
const isRetina = window.devicePixelRatio > 1;

// Use Geoapify tiles — regular or @2x for retina
const baseUrl = `https://maps.geoapify.com/v1/tile/klokantech-basic/{z}/{x}/{y}.png?apiKey=${yourAPIKey}`;
const retinaUrl = `https://maps.geoapify.com/v1/tile/klokantech-basic/{z}/{x}/{y}@2x.png?apiKey=${yourAPIKey}`;

// Add the tile layer
L.tileLayer(isRetina ? retinaUrl : baseUrl, {
  attribution:
    'Powered by <a href="https://www.geoapify.com/" target="_blank">Geoapify</a> | <a href="https://openmaptiles.org/" target="_blank">© OpenMapTiles</a> <a href="https://www.openstreetmap.org/copyright" target="_blank">© OpenStreetMap</a> contributors',
  maxZoom: 20,
  id: "osm-bright",
  apiKey: yourAPIKey
}).addTo(map);

This creates a Leaflet map centered on London using the Geoapify “klokantech-basic” tile style.
The isRetina check ensures that users on high-DPI displays see sharp, high-resolution tiles.

Next, we’ll connect the Geoapify Places API to query and show real places on the map.

Step 2 – Query Places by Category Using the Geoapify Places API

Now that the map is ready, let’s make it interactive by automatically loading places whenever the user pans or zooms.

We’ll connect to the Geoapify Places API and fetch real locations — such as museums, parks, or cinemas — based on the current map view.

1. Listen to map movement events

We want to detect when the user moves or zooms the map, then trigger a new API request.
Leaflet makes this easy with moveend and zoomend events:

map.on("moveend", loadPlaces);
map.on("zoomend", loadPlaces);

Whenever the map position changes, the loadPlaces() function will run and update the visible results.

2. Load places from the Geoapify Places API

Inside loadPlaces(), we:

Get the map’s current bounds.
Define which categories we want to search (for example, museums, cinemas, or parks).
Build and send the API request.

async function loadPlaces() {
  const bounds = map.getBounds();
  const rect = `${bounds.getWest()},${bounds.getSouth()},${bounds.getEast()},${bounds.getNorth()}`;
  const categories = "entertainment.museum,entertainment.cinema,leisure.park";

  const url = `https://api.geoapify.com/v2/places?categories=${categories}&filter=rect:${rect}&limit=100&apiKey=${yourAPIKey}`;

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

  console.log("Places loaded:", data);
}

Tip: The key part is filter=rect:${rect} — it limits the search to the current map bounds, so the API only returns places visible on the map. This makes the search faster, more relevant, and efficient.

You can explore all available categories in the Places API docs.

This is the simplest version of a map-based search — it calls the API every time the user stops moving the map and retrieves up to 100 places in the visible area.

⚙️ In real-world apps

For better performance and smoother user experience, you’ll want to:

Add a short delay (debounce) between map movement and the API request.
Split large map areas into smaller fragments to avoid long or heavy queries.
Limit requests by zoom level (e.g., only start searching when zoom >= 13).
Prevent duplicate results if multiple requests overlap.
Rate-limit API calls to stay within usage limits.

All of these optimizations are implemented in the full CodePen example:
➡️ View the complete version on CodePen

Step 3 – Display places as custom markers (Marker Icon API)

We’ll parse the GeoJSON from the Places API and render each Point as a Leaflet marker.
To make markers visually meaningful, we’ll generate icon URLs on the fly with the Geoapify Marker Icon API.

1) Create a marker icon helper

function markerIconUrl(iconName = "map-marker", color = "#37a961") {
  const icon = encodeURIComponent(iconName);
  const tint = encodeURIComponent(color);
  return `https://api.geoapify.com/v2/icon/?type=awesome&icon=${icon}&color=${tint}&size=50&contentSize=20&scaleFactor=2&apiKey=${yourAPIKey}`;
}

This will create a custom marker icon sized about 38×55 px — the visible icon itself is 38×50 px, and the subtle drop shadow adds roughly 5 px for depth.

The scaleFactor=2 makes icons sharp on retina screens by rendering them at double resolution.

2) Render features as markers with popups

Add this after loadPlaces() fetches the data:

function renderPlaces(geojson) {
  if (!geojson || !Array.isArray(geojson.features)) return;

  // Optional: group for easy clear/redraw on next search
  if (!window.resultsLayer) {
    window.resultsLayer = L.layerGroup().addTo(map);
  } else {
    window.resultsLayer.clearLayers();
  }

  geojson.features.forEach((f) => {
    const { geometry, properties } = f;
    if (!geometry || geometry.type !== "Point") return;

    const [lng, lat] = geometry.coordinates;

    // Pick an icon based on categories (fallback to a generic one)
    const iconName = "map-marker"; // you can map categories -> icon names if you like
    const icon = L.icon({
      iconUrl: markerIconUrl(iconName, "#22c55e"),
      iconSize: [38, 55], // Icon image size in pixels (width x height)
      iconAnchor: [18, 50], // The point of the icon (relative to its top-left corner) that will correspond to the marker’s geographical location
      popupAnchor: [0, -50] // Offset of the popup relative to the icon anchor. Moves the popup slightly above the icon tip
    });

    const name = properties?.name || properties?.address_line1 || "Unnamed place";
    const address = properties?.address_line2 || properties?.formatted || "";

    L.marker([lat, lng], { icon })
      .bindPopup(`<strong>${escapeHtml(name)}</strong><br>${escapeHtml(address)}`)
      .addTo(window.resultsLayer);
  });
}

// Small helper to avoid HTML injection in popups
function escapeHtml(s = "") {
  return String(s)
    .replaceAll("&", "&amp;")
    .replaceAll("<", "&lt;")
    .replaceAll(">", "&gt;")
    .replaceAll('"', "&quot;")
    .replaceAll("'", "&#039;");
}

Call renderPlaces(data) at the end of loadPlaces():

const data = await response.json();
renderPlaces(data);

What you get

Custom icons generated by the Marker Icon API (fast, no image hosting needed).
Informative popups with place names and addresses.
A clean layer group so the map updates neatly on each search.

Tip: For even better UX, map specific categories (e.g., entertainment.museum, leisure.park) to different icon names or colors so users can visually distinguish them at a glance.

Summary

In this tutorial, we built an interactive Leaflet map powered by the Geoapify Places API.
You learned how to:

Set up a map with Geoapify basemap tiles
Query the Places API by category and map bounds
Parse GeoJSON results
Display results as custom markers using the Geoapify Marker Icon API

The result is a map that dynamically shows real places — like museums, cinemas, or parks — with meaningful icons and popups.

For smoother performance and a more responsive UX, check out the advanced version of this project:
➡️ Full CodePen example

In the next tutorial, we’ll dive deeper into performance optimizations — including chunked API requests, rate limiting, and progressive loading for large map areas.

Turn your GeoJSON data into interactive maps — visualize Points, Routes, and Isolines in Leaflet with Geoapify.

Alfiya Tarasenko — Tue, 28 Oct 2025 10:07:06 +0000

How to Visualize GeoJSON Points, Lines, and Polygons on a Leaflet Map

Alfiya Tarasenko for Geoapify Maps API ・ Oct 28

#leaflet #geojson #webdev #programming

How to Visualize GeoJSON Points, Lines, and Polygons on a Leaflet Map

Alfiya Tarasenko — Tue, 28 Oct 2025 10:05:36 +0000

GeoJSON is a lightweight format for encoding geographic data structures such as Points, LineStrings, and Polygons. It’s built on top of JSON and is widely supported across mapping libraries and APIs.

In this tutorial, we’ll explore how to render GeoJSON geometry types on a Leaflet map — including:

Point features representing real-world locations from the Geoapify Places API
LineString features representing travel routes from the Geoapify Routing API
Polygon features representing reachable areas (isochrones or isodistances) from the Geoapify Isoline API

Each Geoapify API returns data as a FeatureCollection, where each Feature includes a geometry object and properties. Leaflet provides native support for GeoJSON via the L.geoJSON() method, making it easy to visualize these geometries directly on a map.

By the end of this tutorial, you’ll have an interactive Leaflet map that displays Points, LineStrings, and Polygons — all styled and layered together using real Geoapify API data.

About Leaflet Functions for Working with GeoJSON
Visualizing GeoJSON Points (Places API)
Visualizing GeoJSON Lines (Routing API)
Visualizing GeoJSON Polygons (Isoline API)
Summary
FAQ

About Leaflet Functions for Working with GeoJSON

Leaflet provides native support for the GeoJSON format through the L.geoJSON() method. It can load any valid GeoJSON Feature, FeatureCollection, or Geometry, automatically creating the correct map layer type — a Marker for Point, a Polyline for LineString, or a Polygon for Polygon.

`L.geoJSON(data, options)`

The L.geoJSON() factory function takes two arguments:

data — a valid GeoJSON object (Feature or FeatureCollection)
options — an optional configuration object that lets you customize how each geometry type is displayed and how features behave

Example:

L.geoJSON(geojsonData, options).addTo(map);

The options parameter supports several useful callbacks and style settings:

`style`

Applies visual styling (color, weight, fill, opacity, etc.) to LineString and Polygon geometries.

const lineLayer = L.geoJSON(routeData, {
  style: function (feature) {
    return { color: '#1976d2', weight: 4, opacity: 0.9 };
  }
}).addTo(map);

Docs: Path options

`pointToLayer`

Controls how Point features are rendered — for example, as custom markers, circle markers, or icons.

const pointsLayer = L.geoJSON(placeData, {
  pointToLayer: function (feature, latlng) {
    return L.circleMarker(latlng, {
      radius: 6,
      fillColor: '#ff5722',
      color: '#fff',
      weight: 1,
      fillOpacity: 0.9
    });
  }
}).addTo(map);

Docs: GeoJSON options

`onEachFeature`

Adds interactivity to each feature — for example, binding popups or click handlers.

const interactiveLayer = L.geoJSON(geojsonData, {
  onEachFeature: function (feature, layer) {
    if (feature.properties && feature.properties.name) {
      layer.bindPopup(feature.properties.name);
    }
  }
}).addTo(map);

Docs: Popup

By combining these options, you can display and style GeoJSON data returned by any of the Geoapify APIs — whether that’s Points from the Places API, LineStrings from the Routing API, or Polygons from the Isoline API.

1. Visualizing GeoJSON Points (Places API)

To start, we’ll visualize GeoJSON Point features returned by the Geoapify Places API.
Each Point represents a real-world place — in this example, schools within a specific area.

Live demo on CodePen: https://codepen.io/geoapify/pen/zxraMEp

In this code sample, each school from the Places API is shown as a stylized marker with a popup showing its name and address.

This demonstrates how to directly visualize API responses that use GeoJSON Point geometries in Leaflet.

GeoJSON Points: Fetching GeoJSON data from the Places API

The Places API endpoint returns a FeatureCollection where each Feature has:

geometry.type = "Point"
geometry.coordinates = [longitude, latitude]
properties describing the place (name, address, category, etc.)

Example fetch request (schools in Jacksonville, US):

const apiKey = "YOUR_API_KEY";
const url = `https://api.geoapify.com/v2/places?categories=education.school&filter=place:51bea59c2ff66954c059d1425dff09553e40f00101f901e0d0010000000000c00208&limit=500&apiKey=${apiKey}`;

fetch(url)
  .then(response => response.json())
  .then(data => {
    L.geoJSON(data, options).addTo(map);
  });

GeoJSON Points: Displaying GeoJSON with `L.geoJSON()`

Leaflet’s L.geoJSON() method automatically recognizes each geometry and adds it to the map.
To customize the rendering of Point features, we use the pointToLayer and onEachFeature options.

L.geoJSON(data, {
  pointToLayer: function (feature, latlng) {
    return L.marker(latlng, { icon: schoolIcon });
  },
  onEachFeature: function (feature, layer) {
    const name = feature.properties.name || "Unnamed school";
    const address = feature.properties.address_line2 || "";
    layer.bindPopup(`<strong>${name}</strong><br>${address}`);
  }
}).addTo(map);

GeoJSON Points: Adding custom marker icons

Instead of default Leaflet pins, we use the Geoapify Marker Icon API
to create branded, retina-friendly icons dynamically by URL.

const schoolIcon = L.icon({
  iconUrl: `https://api.geoapify.com/v2/icon/?type=awesome&color=%23e2b928&size=48&icon=school&iconType=lucide&contentSize=20&noWhiteCircle&scaleFactor=2&apiKey=${yourAPIKey}`,
  iconSize: [36, 53], // width, height in pixels
  iconAnchor: [18, 48], // point of the icon which corresponds to marker’s location, 5px is for shadow
  popupAnchor: [0, -55] // where popups open relative to the iconAnchor
});

This icon configuration:

sets the Lucide "school" icon with a custom orange color (#efa00b),
ensures crisp display on Retina screens,
includes a small decorative shadow for better contrast on light map backgrounds.

2. Visualizing GeoJSON Lines (Routing API)

We’ll render a route as a GeoJSON MultiLineString returned by the Geoapify Routing API and style it with a subtle shadow, rounded caps/joins, and waypoint markers. Turn-by-turn steps are shown both in a sidebar and as small white circle markers on the route.

Live demo (CodePen): https://codepen.io/geoapify/pen/ogbyJeN

This code sample demonstrates:

Calculating route between three waypoints with Geoapify Routing API
Rendering a GeoJSON MultiLineString via L.geoJSON(data, options)
Using the options parameter to style paths and layering the same geometry twice for a subtle shadow effect
Reading waypoint and step metadata from properties to add markers and a turn-by-turn list
Managing visual stacking with custom panes and zIndex

Here are key parts of the example related to GeoJSON LineString visualization:

GeoJSON Lines: Fetch route as GeoJSON

const apiKey = "YOUR_API_KEY";
const url = "https://api.geoapify.com/v1/routing?waypoints=...&mode=drive&apiKey=" + apiKey;

const res = await fetch(url);
const fc = await res.json();
const routeFeature = fc.features[0]; // geometry: MultiLineString

GeoJSON Lines: Draw the route with a shadow underlay

We render the same GeoJSON twice using L.geoJSON(data, options): first a thick semi-transparent shadow, then the colored line above it. Using panes keeps ordering predictable.

map.createPane('route-shadow'); 
map.getPane('route-shadow').style.zIndex = 399;
map.createPane('route-line');   
map.getPane('route-line').style.zIndex   = 400;

const shadow = L.geoJSON(routeFeature, {
  pane: 'route-shadow',
  style: { color: '#000', opacity: 0.25, weight: 10, lineCap: 'round', lineJoin: 'round' }
}).addTo(map);

const line = L.geoJSON(routeFeature, {
  pane: 'route-line',
  style: { color: '#1976d2', opacity: 0.95, weight: 5, lineCap: 'round', lineJoin: 'round' }
}).addTo(map);

Leaflet uses panes to control the drawing order of map layers.
Each pane acts like a separate <div> inside the map container, and layers added to panes with higher zIndex values appear above those in lower ones.

In this example, we create two panes:

route-shadow (zIndex 399) — draws the soft black shadow beneath the line
route-line (zIndex 400) — renders the main colored route above the shadow

By separating the route into multiple panes, we achieve a clear visual hierarchy without merging styles or affecting interactivity.

Learn more in the Leaflet documentation: Map panes.

3. Visualizing GeoJSON Polygons (Isoline API)

We’ll render Polygon/MultiPolygon features returned by the Geoapify Isoline API (drive-time areas) and style them with a soft shadow underlay, semi-transparent fills, and crisp outlines. The map also shows an origin marker and a simple legend for time ranges.

Live demo (CodePen): https://codepen.io/geoapify/pen/EaPROwQ

What happens in the example:

Requests a FeatureCollection from the Isoline API where each feature has geometry.type = Polygon or MultiPolygon and a properties.range (seconds).
Renders polygons via L.geoJSON(data, options) with range-based fillColor, semi-transparent, with outline.
Creates custom panes and z-index so shadows stay beneath fills and markers sit on top.
Adds an origin marker made with the Geoapify Marker Icon API.
Builds a legend from properties.range values and labels them in minutes.

Here are the key code parts used to render GeoJSON Polygons/MultiPolygons from the Isoline API in Leaflet:

GeoJSON Polygons: Fetch Isoline GeoJSON

const apiKey = "YOUR_API_KEY";
const lat = 32.82950455, lon = -96.73469695515405;

const url = `https://api.geoapify.com/v1/isoline?lat=${lat}&lon=${lon}&type=time&mode=drive&range=1200,1800,2400,3000&apiKey=${apiKey}`;

const res = await fetch(url);
const isolineData = await res.json();  // FeatureCollection with Polygon/MultiPolygon

GeoJSON Polygons: Palettes & range mapping (seconds → color)

// Colorful palette (light → dark / inner → outer)
const palette = ['#fff3bf', '#b2f2bb', '#a5d8ff', '#d0bfff', '#ffc9c9', '#ffd8a8'];

const ranges = Array.from(new Set(
  isolineData.features.map(f => f.properties?.range).filter(r => typeof r === 'number')
)).sort((a, b) => a - b);

const colorByRange = {};
ranges.forEach((r, i) => { colorByRange[r] = palette[Math.min(i, palette.length - 1)]; });

const toMinutes = (s) => Math.round(s / 60);

GeoJSON Polygons: Filled polygons with outlines + popups + hover highlight

const fillsLayer = L.geoJSON(isolineData, {
  pane: 'isoline-fill',
  style: (feature) => {
    const r = feature.properties?.range;
    const fill = colorByRange[r] || '#74c0fc';
    return {
      color: '#1e3a8a',   // outline
      weight: 1.5,
      opacity: 0.8,
      fillColor: fill,    // per-range color
      fillOpacity: 0.35
    };
  },
  onEachFeature: (feature, layer) => {
    const r = feature.properties?.range;
    const label = r ? `${toMinutes(r)} min` : 'Isoline';
    layer.bindPopup(`Reachable within ${label}`);

    // subtle hover effect
    layer.on('mouseover', () => layer.setStyle({ weight: 2.5, opacity: 1, fillOpacity: 0.45 }));
    layer.on('mouseout',  () => layer.setStyle({ weight: 1.5, opacity: 0.8, fillOpacity: 0.35 }));
  }
}).addTo(map);

These snippets cover the GeoJSON-specific logic: fetching Polygon/MultiPolygon features, mapping properties.range to colors, drawing a shadow + fill combo for visual depth, and providing popups/hover for interactivity.

Summary

In this tutorial, we explored how to visualize different GeoJSON geometries — Points, LineStrings, and Polygons — using Leaflet and the Geoapify APIs.

GeoJSON Points were loaded from the Geoapify Places API and displayed as custom markers styled via the Geoapify Marker Icon API.
GeoJSON LineStrings were fetched from the Geoapify Routing API and drawn as routes with shadows, colorful lines, and turn-by-turn markers.
GeoJSON Polygons (and MultiPolygons) came from the Geoapify Isoline API, representing areas reachable within certain travel-time ranges.

Each geometry type used Leaflet’s L.geoJSON() with the options parameter to control styling and interactivity — including pointToLayer, style, and onEachFeature.
Together, these techniques demonstrate how Geoapify APIs and Leaflet can be combined to create powerful, visually appealing map visualizations for a wide range of geospatial data.

FAQ

Q: What is GeoJSON and why is it useful?
A: GeoJSON is a standard format for encoding geographic data structures such as Points, LineStrings, and Polygons. It’s easy to parse, visualize, and combine with APIs like Geoapify’s for web mapping.

Q: Which Geoapify APIs provide GeoJSON data?
A:

Places API — returns Points (POIs).
Routing API — returns LineStrings or MultiLineStrings (routes).
Isoline API — returns Polygons or MultiPolygons (travel-time areas).

Q: How does Leaflet handle different geometry types?
A: Leaflet’s L.geoJSON() automatically detects geometry types and renders them appropriately. You can use callbacks like pointToLayer() for Points and style() for LineStrings or Polygons to customize their appearance.

Q: Can I use the same map to show Points, Lines, and Polygons together?
A: Yes. Leaflet allows multiple GeoJSON layers to be added on the same map. You can overlay POIs, routes, and isolines for richer visualization and interactivity.

Q: Why do GeoJSON coordinates sometimes appear flipped when displayed on a Leaflet map?
A: In GeoJSON, coordinates are always defined in [longitude, latitude] order, while Leaflet expects [latitude, longitude]. When you use L.geoJSON() or pass latlng inside pointToLayer or L.marker(), Leaflet automatically converts them correctly. Just make sure you don’t manually reverse the order unless you’re working directly with raw coordinate arrays.

Q: How can I customize the look of my map?
A: You can use the Geoapify Map Tiles to apply different base styles (Bright, Dark, Satellite, etc.) and adjust colors, icons, or shadows for your data layers.

Q: What are some practical use cases for these visualizations?
A:

Points: show places of interest, user locations, or search results.
Lines: display routes, tracks, or transit paths.
Polygons: visualize travel-time zones, service areas, or delivery coverage.

Q: How do I make my layers interactive?
A: Use onEachFeature() in L.geoJSON() to bind popups or highlight layers on hover. This makes maps engaging and helps users explore the data intuitively.

MapLibre GL Markers: Custom Icons, Popups & Events with Geoapify

Alfiya Tarasenko — Wed, 01 Oct 2025 13:45:33 +0000

Markers are one of the most common elements in any interactive map. They help users identify important points, highlight search results, or drop a temporary pin on click.

In MapLibre GL, you can display points on the map in two main ways:

Markers with new maplibregl.Marker() — these are DOM elements (HTML nodes) placed on top of the map at specific coordinates. They are highly customizable, can be interactive, and support drag & drop.
Symbol layers — vector-based icons defined inside a GeoJSON source. They are more efficient for rendering thousands of points but offer less flexibility for custom HTML content.

In this article, we’ll focus on the Marker() API. Markers are ideal when you need interactive or custom pins — for example:

Dropping a pin at a clicked location.
Highlighting search results or selected places.
Adding temporary overlays during editing or debugging.

If you want to style your markers, you can use the Geoapify Map Marker Icon API, which lets you generate dynamically PNG icons with custom colors, sizes, and symbols. These can be easily plugged into MapLibre markers.

To see everything in action, check out the interactive demo: MapLibre Markers with Geoapify on CodePen.

Creating markers
Custom markers
Adding a popup to a marker
Marker events
Managing markers
When not to use markers
FAQ

1. Creating markers

The easiest way to add a marker in MapLibre GL is by creating a new instance of maplibregl.Marker.

The constructor can take an optional configuration object — MarkerOptions — that controls the marker’s appearance (custom HTML, anchor, offset) and behavior (draggable, rotation, alignment).

Once created, you place the marker on the map by setting its position with .setLngLat([lon, lat]) and finalizing it with .addTo(map):

new maplibregl.Marker(markerOptions)
  .setLngLat([lon, lat])
  .addTo(map);

This creates a default blue pin marker at the given coordinates:

MarkerOptions: customizing behavior and appearance

When creating a marker, you can pass an optional MarkerOptions object to control how it looks and behaves. This allows you to change its anchor position, make it draggable, or even replace it entirely with a custom HTML element.

Here are some of the most commonly used options:

Option	Description	Example
`anchor`	Defines which part of the marker should be placed on the given coordinates. Options: `center`, `top`, `bottom`, `left`, `right`, `top-left`, `top-right`, `bottom-left`, `bottom-right`. Default is `center`.	`anchor: "bottom"`
`className`	Space-separated CSS class names to add to the marker element.	`className: "my-marker highlight"`
`draggable`	Makes the marker draggable so users can move it on the map. Default is `false`.	`draggable: true`
`element`	A custom HTML element to use instead of the default blue pin.	`element: myDivElement`
`offset`	Pixel offset from the anchor point. Useful to align custom markers with the correct "tip".	`offset: [0, -10]`

The offset option becomes especially important when you’re using custom marker icons.

By default, a marker is placed with its center aligned to the given coordinates. However, many icons — like pin-shaped markers — need to be aligned at the bottom tip rather than the center.

We’ll explore this in more detail later in the Custom markers section.

📖 There are more options available, such as color, scale, rotation, opacity, pitchAlignment, and others.

See the full list in the official MapLibre MarkerOptions documentation.

2. Custom markers

The most powerful option in MarkerOptions is element.

It allows you to replace the default blue pin with any DOM element — for example, an <img> tag, a styled <div>, or an inline <svg>.

This makes it easy to integrate custom icons, badges, or branded styles.

Example: using Geoapify Marker Icon API

The Geoapify Map Marker Icon API can generate PNG or SVG icons on the fly. You can pick an icon type, set a color, add a shadow, and adjust scaling — then plug the resulting image URL into a MapLibre marker.

// Generate a marker icon URL with Geoapify
function geoapifyIconUrl({ icon, iconType = "material", color = "#8b5cf6" }) {
  const url = new URL("https://api.geoapify.com/v2/icon/");
  url.searchParams.set("type", "awesome");
  url.searchParams.set("icon", icon);
  url.searchParams.set("iconType", iconType);
  url.searchParams.set("color", color);
  url.searchParams.set("shadow", "true");
  url.searchParams.set("scaleFactor", "2");
  url.searchParams.set("apiKey", GEOAPIFY_API_KEY);
  return url.toString();
}

// Create an <img> element for the marker
const img = document.createElement("img");
img.alt = "Restaurant marker";
img.src = geoapifyIconUrl({ icon: "restaurant" });

// Wrap it in a container div
const wrapper = document.createElement("div");
wrapper.className = "map-marker";
wrapper.appendChild(img);

// Create the marker
new maplibregl.Marker({ element: wrapper, anchor: "bottom", offset: [0, -4] })
  .setLngLat([lon, lat])
  .addTo(map);

Here we use anchor: "bottom" and a small negative offset so that the tip of the pin icon aligns exactly with the map coordinates.

👉 Try this in the interactive demo:

Example: adjusting `offset` for custom icons

When you use a custom icon, the default anchor might not match the part of the icon you want to “touch” the map point. That’s where the offset option becomes important.

Case 1: square icon (40×40px)

If you have a round or square icon (e.g. 40×40px) and want it centered exactly on the latitude/longitude, no offset is needed:

const icon40 = document.createElement("img");
icon40.src = "marker-40x40.png";

new maplibregl.Marker({
  element: icon40,
  anchor: "center", // center aligns with lat/lon
  offset: [0, 0]
})
  .setLngLat([lon, lat])
  .addTo(map);

Case 2: pin icon (31×46px with shadow 4px)
For a pin-shaped icon (31×46px, with a shadow extending 4px below), the “tip” of the pin should touch the coordinates.
Here we shift the marker upward so the bottom tip aligns with the point:

const pin = document.createElement("img");
pin.src = "marker-31x46-shadow4.png";

new maplibregl.Marker({
  element: pin,
  anchor: "bottom",       // attach by bottom edge
  offset: [0, -4]         // shift up by shadow size
})
  .setLngLat([lon, lat])
  .addTo(map);

👉 The offset ensures that the visual tip of the marker sits exactly on the coordinates, rather than floating above or overlapping incorrectly.

3. Adding a popup to a marker

Markers in MapLibre can be paired with a Popup so that extra information appears when the user interacts with them.

Popups are not part of the marker itself, but you can attach them using the .setPopup() method.

Example: simple popup

const marker = new maplibregl.Marker()
  .setLngLat([lon, lat])
  .setPopup(
    new maplibregl.Popup({ offset: 25 })
      .setText("Hello from this location!")
  )
  .addTo(map);

// Open the popup immediately
marker.togglePopup();

This creates a marker with a text popup that appears when clicked. In this case, we also call togglePopup() so it opens by default.

Custom popup content

Popups don’t have to be plain text — you can also provide custom HTML using .setHTML(). This makes it possible to render richer content, such as formatted addresses, buttons, or images.

const popup = new maplibregl.Popup({ offset: 25 })
  .setHTML(`
    <div class="popup-content">
      <h3>Restaurant</h3>
      <p>Open daily 10:00–22:00</p>
      <a href="https://example.com" target="_blank">More info</a>
    </div>
  `);

new maplibregl.Marker()
  .setLngLat([lon, lat])
  .setPopup(popup)
  .addTo(map);

Known issue: event propagation

When you click a marker to open its popup, the click event also bubbles up to the map, which may trigger map.on("click", …) handlers.
To avoid unwanted side effects, check whether the click originated from a marker element before running map-level logic:

map.on("click", (event) => {
  // Ignore clicks on existing markers
  if (event.originalEvent.target.closest(".map-marker")) {
    return;
  }

  // ... 
});

This way, clicking on a marker will only open its popup, without triggering your map’s click handler.

4. Marker events

Markers can respond to both DOM events (like clicks or hovers) and drag events if they are created with draggable: true.

DOM events

Attach using marker.getElement():

const marker = new maplibregl.Marker()
  .setLngLat([lon, lat])
  .addTo(map);

marker.getElement().addEventListener("click", () => {
  console.log("Marker clicked!");
});

marker.getElement().addEventListener("mouseenter", () => {
  marker.getElement().style.cursor = "pointer";
});

This way, you can make markers interactive beyond just showing a popup.

Drag events

Available when the draggableoption is true,, the marker can be moved around. You can then listen to the drag lifecycle:

Event name	When it fires
`dragstart`	User starts dragging the marker
`drag`	Marker is being dragged
`dragend`	User releases the marker after dragging

const marker = new maplibregl.Marker({ draggable: true })
  .setLngLat([lon, lat])
  .addTo(map);

// Listen for drag events
marker.on("dragstart", () => console.log("Drag started"));
marker.on("drag", () => console.log("Dragging..."));
marker.on("dragend", () => {
  const lngLat = marker.getLngLat();
  console.log(`New position: ${lngLat.lng}, ${lngLat.lat}`);
});

This is especially useful for “pick a location” UIs, where the user drags a pin to select an exact spot.

📖 See details in the MapLibre Marker docs.

5. Managing markers

When working with more than one marker, it’s good practice to keep track of them so you can update or remove them later.

Keep markers in an array

const markers = [];

function addMarker(lon, lat) {
  const marker = new maplibregl.Marker()
    .setLngLat([lon, lat])
    .addTo(map);

  markers.push(marker);
}

Remove a marker

Each marker has a .remove() method:

markers[0].remove(); // removes the first marker from the map

Remove all markers

markers.forEach(marker => marker.remove());
markers.length = 0; // clear the array

Replace markers dynamically

This is useful when showing search results:

Remove old markers.
Add new ones from the latest data.

Keeping markers organized prevents memory leaks and avoids clutter when updating the map dynamically.

6. When not to use markers

Markers in MapLibre are DOM elements placed on top of the map. This makes them flexible and easy to customize, but also less efficient when you need to display hundreds or thousands of points. Each marker adds a new node to the DOM, which can slow down rendering and interactions.

When to avoid markers

Displaying large datasets (thousands of locations).
Real-time updates where many markers are added/removed frequently.
Use cases where performance and smooth zooming/panning are critical.

Alternative: Symbol layers

For bulk rendering, prefer a GeoJSON source + SymbolLayer.

This approach draws icons directly on the map canvas, which is much more efficient.

map.addSource("places", {
  type: "geojson",
  data: myGeoJson
});

map.addLayer({
  id: "places-layer",
  type: "symbol",
  source: "places",
  layout: {
    "icon-image": "marker-15",
    "icon-size": 1.5
  }
});

Hybrid approach

Use symbol layers for the full dataset.
Use markers for selected or interactive points (e.g., user’s chosen location, currently active place).

FAQ

1. How do I change marker size on high-DPI (retina) displays?

Use a higher-resolution image (2× or SVG) and scale it down with CSS to keep it sharp.

2. Can I drag markers? How do I read their updated coordinates?

Yes — set draggable: true in MarkerOptions and listen to the dragend event. Call marker.getLngLat() to get the new position.

3. What’s the best way to show thousands of points?

Use a GeoJSON source + SymbolLayer, not individual markers.

4. How do I make markers clickable without interfering with the map?

Use marker.getElement().addEventListener("click", …) or attach a popup. In map click handlers, ignore clicks that come from marker elements using event.target.closest(".map-marker").

5. How do I automatically open a popup when a marker is created or added?

After calling .setPopup(), use marker.togglePopup() to open it right away.

6. Can I use inline SVG as a marker?

Yes — pass an element containing your SVG to MarkerOptions.element.

7. How do I rotate a marker with heading or bearing?

Use the rotation option. Combine with rotationAlignment: "map" to keep it aligned to map bearing.

8. Can I animate markers (bounce, pulse, fade)?

Yes — since markers are DOM elements, you can animate them with CSS transitions, keyframes, or libraries like GSAP.

9. How do I add text labels to markers?

Include a <span> or <div> inside your marker element and style it with CSS.

10. How do I cluster many markers?

Don’t cluster DOM markers directly. Instead, cluster your data in GeoJSON and use a SymbolLayer for clustered icons.

11. Can I change marker color dynamically after adding it?

Yes — update the marker’s DOM element (e.g., change an <img> src or CSS class).

12. How do I handle overlapping markers?

Use different offsets, z-index (marker.getElement().style.zIndex), or clustering.

13. How do I remove all markers at once?

Keep them in an array and loop through calling .remove() on each.

14. How do I make markers accessible?

Add alt text for images or aria-label for custom HTML. Use cursor: pointer for clickable markers and keep touch targets large enough on mobile.

Wrap-up

Markers in MapLibre GL are a flexible way to place interactive elements on the map. With MarkerOptions, you can fine-tune alignment, make them draggable, or replace the default pin with your own custom HTML or icons (for example, using the Geoapify Map Marker Icon API).

Use markers when you need:

Interactive pins that users can drag or click.
Custom icons, badges, or HTML content.
Highlighted or temporary overlays.

But remember:

For large datasets, prefer SymbolLayers with a GeoJSON source for performance.
Keep markers organized (arrays, cleanup) to avoid clutter and memory leaks.

In the next article, we’ll take this further and focus on popups — attaching them to markers, rendering custom HTML, and fetching live data (e.g., place details from Geoapify).

How to Fix 401 Unauthorized Error When Calling the API

Alfiya Tarasenko — Mon, 29 Sep 2025 09:49:11 +0000

When working with APIs, running into an HTTP 401 Unauthorized error can be frustrating. It usually means that the request wasn’t authenticated properly — most often because of an issue with your API key.

If you’re using the Geoapify APIs, a 401 error is one of the most common issues new users face. The good news is that it’s quick to fix once you know what to check.

In this short FAQ, we’ll explain what a 401 error means, list the most common causes, and walk you through how to resolve it so you can get your project running smoothly again.

What does “401 Unauthorized” mean?

The 401 Unauthorized status code tells you that the request could not be completed because the server did not receive valid authentication credentials or API key. In other words, the API expected an API key (or another form of authentication), but it was missing, invalid, or rejected.

{
  "statusCode": 401,
  "error": "Unauthorized",
  "message": "Invalid apiKey"
}

It’s important to note that 401 is different from 403:

401 Unauthorized → you are not authenticated (the server doesn’t recognize your credentials).
403 Forbidden → you are authenticated but not allowed to access that resource.

Other common 4xx codes

The 401 Unauthorized error is just one of several client-side HTTP status codes (4xx family). You can find the full list in the Wikipedia page on HTTP status codes.

Here are a few you might encounter most often when working with APIs:

Status Code	Meaning	Typical Cause
400 Bad Request	The server could not understand the request.	Missing or invalid parameters, malformed URL.
401 Unauthorized	Authentication is missing or invalid.	No API key, wrong key, or not sent correctly.
403 Forbidden	You are authenticated but not allowed to access the resource.	Key doesn’t have permission, IP/domain restrictions, or access denied.
404 Not Found	The requested resource doesn’t exist.	Wrong endpoint, typo in URL, or resource removed.
429 Too Many Requests	You have exceeded the allowed request limit.	Hitting rate limits or quota exhaustion.

Understanding these codes helps quickly identify whether the issue is with authentication (401), permissions (403), request formatting (400), missing resources (404), or usage limits (429).

Why 401 stands out

Unlike the other 4xx errors, 401 specifically indicates an authentication problem or problem with API key. It doesn’t mean your request is malformed (400), the resource is missing (404), or you’ve gone over quota (429). It means the API simply doesn’t recognize who you are — usually because the API key is missing, wrong, or invalid.

Common reasons for 401 errors

Here are the most common reasons you might see a 401 Unauthorized when calling an API:

Reason	Description
Missing API key	The request does not include the required `apiKey` parameter. Example: `https://api.geoapify.com/v1/geocode/search?text=Berlin`
Typo in API key	The key is mistyped, cut off, or contains hidden characters (like spaces or line breaks from copy-paste). Example: `apiKey=12345OOPS` instead of `apiKey=12345OPS`
Not URL-encoded	The key or query parameters are not properly URL-encoded, so special characters break the request. Example: When sending an address to Geocoding API it must be URL encoded. In other words, it should be`29%20Buxton%20Road%2C%20London%2C%20E15%201QU%2C%20United%20Kingdom` instead of just 29 Buxton Road, London, E15 1QU, United Kingdom
Key in the wrong place	The API key is sent in the wrong part of the request (e.g., header instead of query parameter). See API authentication basics. Example: sending `Authorization: apiKey` instead of `?apiKey=...`
Inactive key	The key is expired, deleted, or disabled. Learn more about API key lifecycle. Example: using an old key after rotation
Restricted key	The key has domain, IP, or referrer restrictions that block the request. Example: request from `localhost` when the key only allows `example.com`
Environment variable issue	The app doesn’t load the key correctly, often leaving the value empty. Example: request with `apiKey=` and no value

How to fix a 401 error

Here’s a simple step-by-step approach:

Test with curl Run the request directly with curl to see if it works outside your code:

   curl "https://api.geoapify.com/v1/geocode/search?text=29%20Buxton%20Road%2C%20London%2C%20E15%201QU%2C%20United%20Kingdom&format=json&apiKey=YOUR_API_KEY"

If it works here, the issue is in your code.
If it fails, the problem is with your API key or request setup.

If the issue is in your code
Debug and check what request your code actually sends. Compare it with the working curl request to spot the difference.
If the issue is with your API key

Try again with a newly created API key.
Check for domain, IP, or referrer restrictions that may block your request.
If nothing helps, contact Support and share your request details. Geoapify users can email info@geoapify.com.

Summary

A 401 Unauthorized error means your request didn’t pass authentication — most often because the API key is missing, wrong, or restricted.

To solve it, first test the request with curl to see if the problem comes from your code or the API key.

If it’s your code, debug the request it generates.
If it’s the key, try a new one, check restrictions, and if needed, reach out to info@geoapify.com for support.

You can also use the Geoapify API Playground to test requests interactively, generate ready-to-use links, and copy working examples. This is the easiest way to verify your API key and request format.

With these steps, you can quickly identify the root cause and get your API calls working again.

How to Calculate Pixel Width and Height of a Bounding Box at Different Map Zoom Levels

Alfiya Tarasenko — Fri, 26 Sep 2025 07:37:05 +0000

When creating print maps or static map images, one of the key challenges is to control the scale: how many pixels wide and tall will my area of interest be?

Imagine you have a bounding box defined by two latitude/longitude corners. Depending on the zoom, its width and height in pixels will change. Sometimes you know the zoom and want to measure the pixel size; other times you know the desired image width (or height) and want to find the zoom that makes the box fit.

This is exactly what you need when working with the Geoapify Static Maps API — for example:

printing a map at a specific size,
generating static images where labels stay readable,
making sure the requested area fits perfectly into the image dimensions.

In this article, we’ll cover three scenarios with simple JavaScript helpers and a live demo:

Calculate bbox width and height at a given zoom.
Calculate width when the height is fixed.
Calculate height when the width is fixed.

Try it out in the demo: https://codepen.io/geoapify/pen/dPYLYpZ

Background: Zoom Levels, Latitude/Longitude, and Pixels

Most modern map libraries — Leaflet, MapLibre GL, Google Maps, OpenLayers — rely on the Web Mercator projection (EPSG:3857). This projection transforms geographic coordinates (latitude/longitude) into a flat, square map that can be tiled and displayed on screens.

Here’s how it works:

Longitude maps linearly to the X axis. At zoom level 0, the full range −180° … +180° fits into one 256 px tile.
Latitude is projected using the Mercator formula, which stretches distances near the poles. To avoid infinite values, the map is clipped to about ±85.05113° latitude.

A relation between the Mercator projection and the actual relative size of each country. Author: Jakub Nowosad. Source. Licensed under CC BY-SA 4.0:

The result is a grid of tiles, each typically 256×256 px:

At zoom 0, the world is one tile (256 px wide).
At zoom 1, the world is 512 px wide (2 tiles × 256).
At zoom 2, 1024 px wide.
In general:

worldSizePx = 256 × 2^z

So every zoom step doubles the number of pixels available for both longitude and latitude.

👉 See it live: Zoom collage demo (toggle the grid to view tile boundaries).
👉 Read more: Understanding map zoom levels and XYZ tile coordinates.

This transformation from lat/lon to pixels explains why the pixel width/height of a bounding box depends on zoom. A 1° × 1° area near the equator may span only a few pixels at zoom 2, but thousands at zoom 12 — and at high latitudes, the Mercator projection exaggerates this effect even further.

This foundation prepares us for the three practical scenarios:

Calculate pixel width/height of a bounding box at a given zoom.
Given a fixed image height, find the corresponding width.
Given a fixed image width, find the corresponding height.

Case 1: Width and Height at a Given Zoom

The simplest case: you already know the zoom level and want to measure how many pixels wide and tall a geographic bounding box will be.

This requires converting latitude/longitude to world pixel coordinates in Web Mercator. The math looks like this:

Longitude → X (linear):

  x = (lon + 180) / 360 × worldSize

Latitude → Y (Mercator projection):

  y = (0.5 - log((1 + sinφ) / (1 - sinφ)) / (4π)) × worldSize

where φ is the latitude expressed in radians (i.e., φ = lat × π / 180).

Here’s a small utility function in JavaScript:

const TILE_SIZE = 256;

// Convert lon/lat to world pixel coordinates at zoom
function lonLatToWorldPixels(lon, lat, zoom, tileSize = TILE_SIZE) {
  const scale = tileSize * Math.pow(2, zoom);
  const x = (lon + 180) / 360 * scale;

  const sin = Math.sin((lat * Math.PI) / 180);
  const y = (0.5 - Math.log((1 + sin) / (1 - sin)) / (4 * Math.PI)) * scale;

  return { x, y };
}

// Calculate bbox width/height in pixels at a given zoom
function bboxSizePx(bbox, zoom, tileSize = TILE_SIZE) {
  const [minLon, minLat, maxLon, maxLat] = bbox;
  const p1 = lonLatToWorldPixels(minLon, minLat, zoom, tileSize);
  const p2 = lonLatToWorldPixels(maxLon, maxLat, zoom, tileSize);
  return {
    width: Math.abs(p2.x - p1.x),
    height: Math.abs(p2.y - p1.y)
  };
}

Example

Let’s measure a box around Paris:

const bboxParis = [2.1, 48.7, 2.5, 49.0]; // [minLon, minLat, maxLon, maxLat]

console.log(bboxSizePx(bboxParis, 5));
// → { width: 9.10 px, height: 10.37 px }

console.log(bboxSizePx(bboxParis, 10));
// → { width: 291.27 px, height: 331.98 px }

At zoom 5, the Paris bbox is just a few pixels across. At zoom 10, it’s already several hundred pixels.

This explains why, when printing or generating static images, choosing the right zoom is crucial: too low and your area looks tiny, too high and it won’t fit into the image dimensions.

Case 2: Width from a Given Height

Sometimes you don’t fix the zoom directly — instead, you know how tall the image should be in pixels. From that height, you can derive the corresponding width of the bounding box (or the zoom that gives you that height).

The math works because in Web Mercator, both width and height scale proportionally with 2^z. If you know one dimension, you can compute the zoom and then derive the other.

JavaScript helper

// Precompute bbox deltas at zoom 0
function bboxDeltaAtZoom0(bbox, tileSize = TILE_SIZE) {
  const [minLon, minLat, maxLon, maxLat] = bbox;

  const x0a = tileSize * (minLon + 180) / 360;
  const x0b = tileSize * (maxLon + 180) / 360;
  const dx0 = Math.abs(x0b - x0a);

  const mercY = (lat) => {
    const s = Math.sin((lat * Math.PI) / 180);
    return (0.5 - Math.log((1 + s) / (1 - s)) / (4 * Math.PI)) * tileSize;
  };
  const dy0 = Math.abs(mercY(maxLat) - mercY(minLat));

  return { dx0, dy0 };
}

// Given a bbox and target height, find zoom
function zoomForHeight(bbox, targetHeightPx, tileSize = TILE_SIZE) {
  const { dy0 } = bboxDeltaAtZoom0(bbox, tileSize);
  return Math.log2(targetHeightPx / dy0);
}

// From that zoom, calculate width
function widthFromHeight(bbox, targetHeightPx, tileSize = TILE_SIZE) {
  const z = zoomForHeight(bbox, targetHeightPx, tileSize);
  const { width } = bboxSizePx(bbox, z, tileSize);
  return { zoom: z, width };
}

Example

const bboxParis = [2.1, 48.7, 2.5, 49.0]; // Paris bbox

const result = widthFromHeight(bboxParis, 600);
console.log(result);
// → { zoom:  10.854, width: 526.42 px }

This tells us:

If we want the Paris bbox to be 600 px tall, we need roughly zoom 10.9.
At that zoom, its width will be ~526 px.

Why it’s useful

This scenario is handy when you know the image height (e.g., fixed paper size, or a portrait-oriented static map) and want the width to scale accordingly.

Case 3: Height from a Given Width

In many layouts the image width is fixed (website container, print column). From that width, you can solve the zoom first and then derive the height of your bounding box.

JavaScript helpers

// Precompute bbox deltas at zoom 0 (reuse if already defined)
function bboxDeltaAtZoom0(bbox, tileSize = 256) {
  const [minLon, minLat, maxLon, maxLat] = bbox;

  const x0a = tileSize * (minLon + 180) / 360;
  const x0b = tileSize * (maxLon + 180) / 360;
  const dx0 = Math.abs(x0b - x0a);

  const mercY = (lat) => {
    const s = Math.sin((lat * Math.PI) / 180);
    return (0.5 - Math.log((1 + s) / (1 - s)) / (4 * Math.PI)) * tileSize;
  };
  const dy0 = Math.abs(mercY(maxLat) - mercY(minLat));

  return { dx0, dy0 };
}

// Solve zoom for a target pixel width
function zoomForWidth(bbox, targetWidthPx, tileSize = 256) {
  const { dx0 } = bboxDeltaAtZoom0(bbox, tileSize);
  return Math.log2(targetWidthPx / dx0);
}

// From that zoom, calculate height
function heightFromWidth(bbox, targetWidthPx, tileSize = 256) {
  const z = zoomForWidth(bbox, targetWidthPx, tileSize);
  const { height } = bboxSizePx(bbox, z, tileSize); // reuse bboxSizePx from Case 1
  return { zoom: z, height };
}

Example

const bboxParis = [2.1, 48.7, 2.5, 49.0]; // [minLon, minLat, maxLon, maxLat]

const result = heightFromWidth(bboxParis, 800);
console.log(result);
// → { zoom: 11.458, height: 911.81 px }

Interpretation:

To make the Paris bbox 800 px wide, you need zoom ≈ 11.5.
At that zoom, the bbox will be about 912 px tall.

When this helps

Fixed-width web containers (responsive pages where height can grow).
Landscape static map images that must match a target width.
Print layouts where column width is constrained and height can flow.

Demo walkthrough

To make the math more intuitive, we prepared a live demo you can explore in your browser:

To make the math more intuitive, here’s a live demo you can try directly:

What it shows:

Case 1: calculate width and height of a bounding box at a given zoom.
Case 2: calculate width when a target height is specified.
Case 3: calculate height when a target width is specified.

How to use it:

Enter or adjust the bounding box coordinates.
Select a zoom level or provide a target width/height.
See how the bbox dimensions in pixels update instantly.

This interactive tool helps visualize the link between geographic coordinates, zoom levels, and pixel sizes — the same logic you can reuse in code when preparing static images or print maps.

Conclusion

Working with bounding boxes in Web Mercator isn’t just about coordinates — it’s also about pixels.
In this article we covered three practical scenarios:

Width/height at a given zoom → useful when you already know the zoom and want to measure how large your area will appear.
Width from a given height → handy when your image or print layout has a fixed height.
Height from a given width → perfect for fixed-width web containers or landscape images.

These calculations are especially important when printing maps or generating static images with the Geoapify Static Maps API. They let you:

pick the right zoom to make your area fit,
avoid cutting off important features,
ensure labels and markers stay legible.

And with the demo, you can experiment in real time to see how zoom, width, and height interact.

👉 Explore more mapping tools and APIs at Geoapify.

Free OpenStreetMap Locality Dataset: Cities, Towns, Villages & Hamlets in NDJSON

Alfiya Tarasenko — Fri, 19 Sep 2025 09:22:48 +0000

Keeping city, town, and village information up to date is harder than it sounds. The raw data inside OpenStreetMap is incredibly rich, yet developers still spend hours cleaning duplicates, merging boundaries, and normalizing metadata before it becomes production-ready.

To make that easier, Geoapify publishes a free OpenStreetMap locality dataset: NDJSON archives that bundle cities, towns, villages, and hamlets for every country, complete with administrative boundaries and multilingual labels. You can browse and download every country bundle from our data hub at Download all the cities, towns, villages.

What's inside the bundles
Working with NDJSON
What each record contains
Enriching records with Geoapify Place Details
Suggested applications
Quality notes
Attribution and licensing

What's inside the bundles

Every country is packaged as a zip file at:

https://www.geoapify.com/data-share/localities/<country_code>.zip

For example, https://www.geoapify.com/data-share/localities/de.zip contains the German locality files.

After unzipping you will always find four NDJSON files:

<country_code>/
├── place_city.ndjson
├── place-town.ndjson
├── place-village.ndjson
└── place-hamlet.ndjson

Here is an example of data:

{"name":"Aurora","other_names":{"name:en":"Aurora","name:ru":"Орора"},"display_name":"Aurora, Aurora Township, Kane County, Illinois, United States","address":{"city":"Aurora","municipality":"Aurora Township","county":"Kane County","state":"Illinois","ISO3166-2-lvl4":"US-IL","country":"United States","country_code":"us"},"population":180542,"osm_type":"node","osm_id":153812116,"type":"city","location":[-88.3147539,41.7571701],"bbox":[-88.4747539,41.5971701,-88.1547539,41.9171701],"border":{"name":"Aurora","other_names":{"name:en":"Aurora","name:ru":"Орора"},"display_name":"Aurora, Aurora Township, Kane County, Illinois, United States","address":{"city":"Aurora","municipality":"Aurora Township","county":"Kane County","state":"Illinois","ISO3166-2-lvl4":"US-IL","country":"United States","country_code":"us"},"population":180542,"osm_type":"relation","osm_id":124817,"type":"administrative","location":[-88.3147539,41.7571701],"bbox":[-88.4083712,41.679869,-88.204992,41.8221793]}}
{"name":"Austin","other_names":{"name:ar":"أوستن","name:be":"Остын","name:bn":"অস্টিন","name:de":"Austin","name:el":"Ώστιν","name:en":"Austin","name:eo":"Aŭstino","name:es":"Austin","name:fa":"آستین","name:fr":"Austin","name:he":"אוסטין","name:hi":"ऑस्टिन","name:it":"Austin","name:ja":"オースティン","name:ko":"오스틴","name:ku":"Austin","name:la":"Austinopolis","name:pl":"Austin","name:pt":"Austin","name:ru":"Остин","name:sr":"Остин","name:ta":"ஆஸ்டின்","name:te":"ఆస్టిన్","name:tr":"Austin","name:uk":"Остін","name:ur":"آسٹن","name:vi":"Austin","name:zh":"奥斯汀 / 柯士甸","name:azb":"آستین","name:grc":"Αὐγούστα","name:hak":"Austin","name:nan":"Austin","name:yue":"柯士甸","name:zh-Hans":"奥斯汀","name:zh-Hant":"奥斯汀","name:be-tarask":"Остын","name:zh-Hant-HK":"柯士甸"},"display_name":"Austin, Travis County, Texas, United States","address":{"city":"Austin","county":"Travis County","state":"Texas","ISO3166-2-lvl4":"US-TX","country":"United States","country_code":"us"},"population":974447,"osm_type":"node","osm_id":1801308037,"type":"city","location":[-97.7436995,30.2711286],"bbox":[-97.9036995,30.1111286,-97.5836995,30.4311286],"border":{"name":"Austin","other_names":{"name:ar":"أوستن","name:be":"Остын","name:de":"Austin","name:el":"Ώστιν","name:en":"Austin","name:es":"Austin","name:ru":"Остин","name:sr":"Остин","name:uk":"Остін","name:ur":"آسٹن","name:zh":"奥斯汀 / 柯士甸","name:azb":"آستین","name:grc":"Αὐγούστα","name:hak":"Austin","name:nan":"Austin","name:yue":"柯士甸","name:zh-Hans":"奥斯汀","name:zh-Hant":"奥斯汀","name:bn":"অস্টিন","name:eo":"Aŭstino","name:fa":"آستین","name:fr":"Austin","name:he":"אוסטין","name:hi":"ऑस्टिन","name:it":"Austin","name:ja":"オースティン","name:ko":"오스틴","name:ku":"Austin","name:la":"Austinopolis","name:pl":"Austin","name:pt":"Austin","name:ta":"ஆஸ்டின்","name:te":"ఆస్టిన్","name:tr":"Austin","name:vi":"Austin","name:be-tarask":"Остын","name:zh-Hant-HK":"柯士甸"},"display_name":"Austin, Travis County, Texas, United States","address":{"city":"Austin","county":"Travis County","state":"Texas","ISO3166-2-lvl4":"US-TX","country":"United States","country_code":"us"},"population":974447,"osm_type":"relation","osm_id":113314,"type":"administrative","location":[-97.7436995,30.2711286],"bbox":[-97.9367663,30.0985133,-97.5605288,30.5166255]}}

This structure makes it easy to load only the locality types you need without preprocessing.

Working with NDJSON

Every file is a newline-delimited JSON stream. Instead of a single giant JSON array, each line is a self-contained JSON object. That makes the dataset friendly for streaming, piping between tools, or chunked imports.

Stream with Node.js

import fs from "fs";
import readline from "readline";

async function processFile(path) {
  const stream = fs.createReadStream(path, "utf8");
  const rl = readline.createInterface({ input: stream });

  for await (const line of rl) {
    if (!line.trim()) continue;
    const place = JSON.parse(line);
    // Work with the place object: console.log(place.name);
  }
}

processFile("de/place_city.ndjson");

Read with Python

import json

with open("de/place-town.ndjson", "r", encoding="utf-8") as fh:
    for row in fh:
        row = row.strip()
        if not row:
            continue
        place = json.loads(row)
        # Example usage: print(place["name"], place.get("population"))

Filter with jq

jq 'select(.population and .population > 500000) | {name, population}' \
  de/place_city.ndjson

Because the files are pure NDJSON you can plug them into data pipelines, message queues, or databases that accept JSON Lines (e.g. BigQuery, Elasticsearch, Snowflake, or PostgreSQL COPY with FORMAT json).

OSM tags used to compile the bundle

Every archive focuses on populated places captured by place=* tags in OpenStreetMap:

In addition to these nodes, OpenStreetMap stores many municipal boundaries as boundary=administrative relations. When such a boundary references a locality (via matching names, linked_place, or similar tags) we pair it with the corresponding place record and expose it under a border property. Depending on how many matching relations we find, border can be a single object or an array of administrative relations.

Not every boundary has an explicit place=* tag, but they are still valuable: in many regions administrative relations are the only dataset that hints at a settlement. If we detect one of those boundaries and can infer that it represents a city, town, village, or hamlet, we add it to the dataset with an inferred_type field so you can decide whether to keep or discard it.

What each record contains

Every NDJSON line holds a single locality object. Key fields include:

Field	Description
`osm_type`, `osm_id`	OSM identifiers for the node/way/relation
`type`	The `place=*` value (`city`, `town`, `village`, `hamlet`)
`name`, `other_names`	Primary place name plus language-specific variants
`display_name`	A full, human-readable label similar to Nominatim output
`address`	Structured address metadata (country code, region, admin levels)
`population`	Reported population (when present in OSM)
`location`	`[lon, lat]` point coordinate
`bbox`	`[min_lon, min_lat, max_lon, max_lat]` bounding box
`border`	Administrative relation(s) that represent the area of the locality
`inferred_type`	Present when the system had to infer the place type from address hints

All files are newline-delimited JSON, which makes them easy to stream with tools like jq, Python's json module, Node.js streams, or any big-data ingestion pipeline.

Sample record

{
  "name": "Aachen",
  "display_name": "Aachen, Städteregion Aachen, Nordrhein-Westfalen, Deutschland",
  "address": {
    "city": "Aachen",
    "state": "Nordrhein-Westfalen",
    "country": "Deutschland",
    "country_code": "de"
  },
  "osm_type": "relation",
  "osm_id": 62764,
  "type": "city",
  "location": [6.08388, 50.77535],
  "population": 249646,
  "bbox": [6.00164, 50.70452, 6.21609, 50.84047],
  "border": {
    "osm_type": "relation",
    "osm_id": 62765,
    "type": "administrative", ...
  }
}

Feel free to trim the fields you do not need—each line is independent, so you can stream-filter the dataset using the tools you already know.

Enriching records with Geoapify Place Details

The dataset already includes plenty of metadata, but you can dig deeper with Geoapify's Place Details API. Feed it the osm_id and osm_type from any record to retrieve enhanced attributes, opening hours, and geometry.

Example call, for Paris, France:

https://api.geoapify.com/v2/place-details?osm_id=7444&osm_type=r&apiKey=YOUR_API_KEY

Here is the geometry for the place:

Replace YOUR_API_KEY with a valid Geoapify key and customize the OSM identifiers to match the locality you care about. When a record already carries a border object you can use the identifier inside the border to request full administrative polygons.

Suggested applications

Quick visualization. Drop any NDJSON file into a Leaflet or MapLibre map to display centroids and polygons.
Spatial analytics. Load the dataset into PostGIS or BigQuery to join with demographic or business data.
Geofencing. Use the embedded border geometries to decide whether a user falls inside a particular locality.
Search and localization. The other_names field gives you multilingual labels and historical aliases.
Data quality monitoring. Compare population figures across snapshots to spot OSM changes or anomalies.
Offline and edge deployments. Because the data is NDJSON, you can ship only the countries you need to client devices without restructuring the format.

Quality notes

Administrative attachments rely on name matching plus geometry overlap; a handful of localities may not have a border if the OSM relation is missing or mismatched.
Population values are only as accurate as the OSM tags. Treat them as hints unless you verify against official statistics.
inferred_type appears when the place lacked a definitive place=* tag. You can filter these out if you only want explicit matches.

Attribution and licensing

These extracts are derived from OpenStreetMap and distributed under the Open Database License (ODbL). Always credit “© OpenStreetMap contributors” and share derivative databases under the same license when you publish them publicly.

A minimal attribution example:

© [OpenStreetMap contributors](https://www.openstreetmap.org/copyright). Locality dataset processed by [Geoapify](https://www.geoapify.com). Licensed under [ODbL](https://opendatacommons.org/licenses/odbl/).

The next articles in this series will explore practical workflows: loading the NDJSON into databases, visualizing boundaries, and combining the dataset with live Geoapify APIs. Stay tuned!

Forem: Alfiya Tarasenko

Got coordinates but need a city or ZIP code? This guide shows how to convert lat/lon into address data using reverse geocoding — with real examples, API calls, and a live demo.

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

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

Coordinates vs Address: Two Ways to Describe a Location

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

Getting city from coordinates

Getting postcode (ZIP code) from coordinates

Getting address from coordinates

Common Pitfalls When Converting Coordinates to Address

City is not always available

The result depends on the exact point

The closest result may not match expectations

Coordinates may need normalization

Try It Yourself: Interactive Reverse Geocoding Demo

Summary

Additional Resources

FAQ

Is reverse geocoding free?

How do I get an API key?

How do I get the timezone from coordinates?

How do I get the state or region?

How can I understand the quality of the result?

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

Can I use reverse geocoding offline?

What happens if there are no results?

Loading hundreds of places on a map? Learn how to make it fast and smooth! This tutorial shows how to use the Geoapify Places API with Leaflet, split map areas into chunks, and apply rate limiting for better performance and UX.

Handle Large Place Searches: Chunked and Rate-Limited Search in Leaflet

Handle Large Place Searches: Chunked and Rate-Limited Search in Leaflet

🧭 Table of Contents

Why large place searches can be slow

A better approach

Split the map bounds into smaller fragments

What this does

Run fragment requests with rate limiting

See the full implementation

Summary

[Boost]

How to Query and Display Nearby Places on a Leaflet Map with the Geoapify Places API

Alfiya Tarasenko for Geoapify Maps API ・ Nov 5

How to Query and Display Nearby Places on a Leaflet Map with the Geoapify Places API

🧭 Table of Contents

Step 1 – Set up the Leaflet Map

Step 2 – Query Places by Category Using the Geoapify Places API

1. Listen to map movement events

2. Load places from the Geoapify Places API

⚙️ In real-world apps

Step 3 – Display places as custom markers (Marker Icon API)

1) Create a marker icon helper

2) Render features as markers with popups

What you get

Summary

Turn your GeoJSON data into interactive maps — visualize Points, Routes, and Isolines in Leaflet with Geoapify.

How to Visualize GeoJSON Points, Lines, and Polygons on a Leaflet Map

Alfiya Tarasenko for Geoapify Maps API ・ Oct 28

How to Visualize GeoJSON Points, Lines, and Polygons on a Leaflet Map

Table of Contents

About Leaflet Functions for Working with GeoJSON

L.geoJSON(data, options)

style

pointToLayer

onEachFeature

1. Visualizing GeoJSON Points (Places API)

GeoJSON Points: Fetching GeoJSON data from the Places API

GeoJSON Points: Displaying GeoJSON with L.geoJSON()

GeoJSON Points: Adding custom marker icons

2. Visualizing GeoJSON Lines (Routing API)

GeoJSON Lines: Fetch route as GeoJSON

GeoJSON Lines: Draw the route with a shadow underlay

3. Visualizing GeoJSON Polygons (Isoline API)

GeoJSON Polygons: Fetch Isoline GeoJSON

GeoJSON Polygons: Palettes & range mapping (seconds → color)

GeoJSON Polygons: Filled polygons with outlines + popups + hover highlight

Summary

FAQ

MapLibre GL Markers: Custom Icons, Popups & Events with Geoapify

Table of Contents

1. Creating markers

MarkerOptions: customizing behavior and appearance

2. Custom markers

`L.geoJSON(data, options)`

`style`

`pointToLayer`

`onEachFeature`

GeoJSON Points: Displaying GeoJSON with `L.geoJSON()`

Example: adjusting `offset` for custom icons