Feature
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.
Detail
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.
# 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"Detail
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.
Detail
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.
Guides
See it in code
Questions
Self-hosting with .glx: 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.
Sources
- RFC 9110 §14: Range Requests, IETF (read 2026-10-22)
Geocode your first address in a minute.
100,000 requests a month free. Commercial use with attribution. No card.