Geocoder

Geocoding service consisting of a Photon backend search engine and a Proxy frontend.

Deployment

All deployment runs from the main branch.

Proxy

Automatic — Push to main → builds and deploys to dev → tst → prd, with acceptance tests after each.

Manual:

• proxy-build.yml — Build and deploy (target: dev only | dev → tst → prd | tst → prd)
• proxy-deploy.yml — Deploy an existing image tag

Photon

Scheduled — Daily at 07:27 UTC: full data import + build + deploy to tst → prd. Checks out the prod-approved tag (updated by Proxy CI after successful prod deploy) to avoid using untested commits.

Manual:

• photon.yml — Import data, build Photon image, deploy (target: dev only | dev → tst → prd | tst → prd)
• photon-rebuild.yml — Rebuild Photon image from existing Nominatim data, deploy
• photon-deploy.yml — Deploy an existing Photon image tag

Sweden (dev only)

• photon-sweden.yml — Import/rebuild/deploy Photon for Sweden
• proxy-sweden.yml — Build/deploy Proxy for Sweden

Usage

Running locally

# Build geocoder
./gradlew build

# Download a photon jar
cd photon
./import/download-photon-jar.sh

# EITHER download source data, convert to nominatim.ndjson (downloads nominatim-converter binary automatically)
./import/create-nominatim-data.sh import/config/sources-prod.conf -z

# OR download the latest nominatim.ndjson build by Github Actions
./download-latest-nominatim-data.sh

# Create the photon index
./import/create-photon-data.sh nominatim.ndjson.gz

# OR just download the latest Photon search index built by Github Actions
rm -rf photon_data
./download-latest-photon-data.sh

# Run Photon
./photon-start.sh

# Switch to a different terminal and start the proxy (or just run `no.entur.geocoder.proxy.AppKt` from your IDE)
cd ../proxy
java -jar build/libs/proxy-all.jar

Now try some example requests:

curl -s 'http://localhost:8080/v2/autocomplete?text=sk%C3%B8yen%20stasjon&size=20'
curl -s 'http://localhost:8080/v2/reverse?point.lat=59.92&point.lon=10.67&boundary.circle.radius=1&size=10&layers=address%2Clocality'

Adding &debug=true will also reveal native Photon results with importance (input weight) and score (calculated weight).

You can also access Photon directly:

curl -s 'http://localhost:2322/api?q=Berglyveien&include=layer.stopplace'

Or use the opensearch endpoint:

curl -s 'http://localhost:9201/photon/_mapping' | jq .       # Available fields
curl -s 'http://localhost:9201/photon/_doc/719158973' | jq . # Get document by ID

Debugging data in k8s / GKE

Accessing the opensearch queries in k8s:

kubectl --context dev port-forward geocoder-photon-85994c94dd-6lqhv -n geocoder 9201
curl -s 'https://geocoder-photon.dev.entur.io/api?q=ullerud' |jq  '.features[].properties.osm_id' |head -1
200127208213
curl -s 'http://localhost:9201/photon/_doc/200127208213' |jq -c "[._source.importance, ._source.name.default]"
[0.23010299956639815,"Ullerud terrasse"]

Verifying score and importance

We set the importance field in the Nominatim data, while score is calculated by Photon.

$ curl -s 'http://localhost:8080/v2/autocomplete?text=Oslo&debug=true&size=1' \
  | jq -c '.geocoding.debug.raw_data[] | [.localeTags.name.default, .infos.importance, .score]'
["Oslo",1.0,51.235104]
["Oslo lufthavn",0.347712,26.492702]
["Oslo S",0.330103,25.840235]
["Oslo bussterminal",0.330103,24.307642]

_{^{(Debug shows three more results than we ask for, see PhotonAutocompleteRequest.RESULT_PRUNING_HEADROOM)}}

Using a patched Photon version

Build and release patched Photon

• Fetch Photon from source (https://github.com/komoot/photon) and make your changes
• Build with ./gradlew build
• Create a tag and push that (git push --tags entur) to EnTur's fork (https://github.com/entur/photon)
• Draft a new release at https://github.com/entur/photon/releases/new
• Click "Select tag" --> and select the tag name
• Fill in release title and description
• Add photon-<tag>.jar from Photon's target/ folder as a binary asset
• Check "Set as a pre-release"
• Publish the release
• On the release page, right-click the photon-<tag>.jar asset and copy the link address

Update geocoder to use the patched Photon

• Go to photon/import/download-photon-jar.sh and update the PHOTON_JAR variable with the new link
• Push your geocoder changes
• Go to https://github.com/entur/geocoder/actions/workflows/photon-dev.yml and trigger the workflow for DEV deployment.

Links

Grafana dashboards

• Photon metrics
• Proxy metrics
• v1 vs v2 metrics
• pelias parameter usage

Internal references

• v1 vs v2 comparison tool (bau)
• bau repo
• Boost calculation in kakka
• Boost config in kakka
• geocoder acceptance tests
• pelias-api @ entur

External references

• photon
• photon pelias adapter
• list of photon alt names
• OSM dumps for photon from graphhopper
• Nominatim DB fields (database layout)
• Photon JSON import PR (outdated)
• Nominatim search tool