# A geocoder that is one static file

> geolith packs a whole geocoding index into one static .glx file and answers each query with HTTP range reads into it: no database, no Elasticsearch, no import step. The planet file measured on 22 Oct 2026 is 31.63 GB with 678,043,458 places, built in 5 h 28 min on one Mac; it answered 21 of 21 world test queries correctly, the slowest in 110 ms on a warm local server. The same file powers geolith cloud on Cloudflare’s edge.

## What is a .glx file?

A .glx file is geolith’s single-file geocoding index: the search index, the place records, the outlines and a spatial index packed into one static file. A server answers each query with a few HTTP range requests into the file, so no database or search cluster is needed. The planet file is 31.63 GB with 678,043,458 places.

## How it works

A .glx file is to geocoding what a PMTiles archive is to map tiles. The index, the records and the outlines sit in one file with a small header. A query reads the header, then only the blocks it needs, so the file can live on a disk, on S3 or R2, or behind any server that supports HTTP range requests.

Self-host:

```bash
# One static file. No database, no Elasticsearch, no import step.
# The search server answers each query with HTTP range reads into the file.
GLX_FILE=./india.glx LISTEN=127.0.0.1:4000 geolith-search

curl "http://127.0.0.1:4000/v1/search?text=pune"
```

## Why one file

Classic self-hosted geocoders need a database or a search cluster, an import that takes hours to days, and a machine sized to keep the index hot. A static file has none of that: copy it, point the server at it, and roll back by pointing at the previous file.

- No database to tune, back up or upgrade.
- Deploy and roll back by swapping one file.
- Reads are bounded per query, so cost per query is predictable.
- The same file works locally, in a container or at the edge.
- Open any .glx file in the browser, local or by https URL, and query it with the viewer at https://demo.geolith.app/glx/; the file is read in byte ranges and never uploaded.

## Getting the server and files

The server, the file format and how to build a country file are documented at docs.geolith.app/search. For access to the server and prebuilt files, write to contact@geolith.app. If you would rather not run anything, geolith cloud serves the same API.

## Questions

### How big is the planet .glx file?

31.63 GB with 678,043,458 places, measured on 22 Oct 2026 in the current format.

### Do I need Elasticsearch or PostgreSQL?

No. geolith search reads the .glx file directly with range reads. There is no database and no import step.

### Is the self-hosted API the same as geolith cloud?

Yes, the routes and response shapes are the same, so you can move between them by changing the base URL and the key.

## Guides

- https://geolith.app/guides/how-to-build-a-geocoder

## Sources

1. [RFC 9110 §14: Range Requests](https://www.rfc-editor.org/rfc/rfc9110#name-range-requests), IETF (read 2026-10-22)

Get a free API key (100,000 requests a month): https://console.geolith.app/signup