Bookerty: Geocoding Stack

A new custom geocoding stack built for use by the Bookerty platform, as part of their mapping overhaul effort. Google Maps was costly to be used as a primary resolver and it does not offer region polygon geometries for accurate listing filtering.

I developed a custom-fit geocoding stack based on open source projects:

• OpenStreetMap for map data via geofabrik pbf file snapshots
• Nominatim for extracting and modelling the data for geocoding, as well as serving polygons
• Photon as a fast and flexible search service layer

The stack is deployed using a simple Docker Compose setup and can use any OSM-compatible pbf as original topographic data. It is also dev-grade by design: localhost ports, no TLS, auth, CORS or rate limiting. Anything public needs a reverse proxy first, but that was decided so that the service can be adapted and hosted in many different scenarios by the client.

The Bookerty backend talks to the two services directly, with no facade in between. A search first hits Photon, with a layer filter that depends on who is searching: guests looking for a destination only get cities, districts and localities, while hosts entering an address only get streets and houses. When the app needs the actual region shape for listing filtering, it passes the result’s OSM identity (osm_type + osm_id) straight to Nominatim’s /lookup and gets the polygon back, simplified with polygon_threshold so island boundaries stay small. Destinations that are only a bare OSM node have no polygon, so Photon returns no extent for them and the app skips the Nominatim call and filters by distance instead.

Greek language spelling was a big pain point when building this stack, and alternatives such as Pelias were considered. The most rewarding solution that made most sense for integration with the Bookerty app was to create an alias csv with rows keyed by OSM identity, each tagged translit, exonym, historic or unaccented (Xania, Korfu, Candia, unaccented Ιος), plus mp/mb spellings like Olymbos. Other options like using photon’s synonym file would not work in autocomplete, and an overwrite of the pbf source would break updates. Photon’s entrypoint now hashes the CSV and, when it changed, writes each alias into Nominatim’s placex.name right before the index build. Aliases rank below primary names and only reach Photon.