OTS Geolocation for Frappe – automatic geocoding for standard Address records

Frappe Framework
1

Hi everyone,

I recently built a small Frappe-only app called OTS Geolocation for Frappe.

The idea came from a simple gap I ran into: Frappe already has Geolocation Settings, provider configuration, Leaflet/OSM support and a Geolocation field type, but I wanted standard Address records to automatically receive coordinates that can then be reused by other apps.

So instead of introducing another location model or separate provider configuration, the app stays deliberately thin:

Frappe Address
      ↓
OTS Geolocation
      ↓
Frappe Geolocation Settings
      ↓
configured provider
      ↓
Address.location

The result is stored directly in the standard Frappe Address.location field as GeoJSON. The app reuses Frappe’s existing provider configuration and does not introduce another credentials/settings layer.

Main features

  • Adds location (Geolocation) to the standard Address DocType.
  • Includes provider adapters for Geoapify, HERE and Frappe v16’s Nomatim / Nominatim option.
  • Can automatically geocode an Address after creation or when postal fields change.
  • Adds a manual “Koordinaten abrufen” / fetch coordinates action to Address.
  • Preserves manually entered coordinates.
  • Does not bulk-geocode existing addresses during installation.
  • Uses normal Frappe permissions and background jobs.
  • No ERPNext dependency.
  • No GRX dependency.
  • No Frappe Core patch.

One thing that was important to me was not to create a second location abstraction. Address.location remains the canonical coordinate field, so other Frappe apps can simply consume the coordinates without knowing anything about OTS Geolocation.

Current status

This is an early v1 release.

It is currently developed and tested on Frappe v16.34.0. My practical real-world testing so far has mainly been done with Geoapify.

Support for HERE and Nominatim is implemented, but those providers should currently be considered less thoroughly tested. I would especially appreciate feedback from anyone trying them in a real Frappe installation.

The scope is intentionally small for now: standard Frappe Address, standard Geolocation Settings, and Address.location as the canonical coordinate field.

Automatic geocoding

If automatic coordinate completion is enabled, the flow is basically:

Address created / postal address changed
        ↓
Frappe default queue
        ↓
configured geocoding provider
        ↓
Address.location

Unrelated saves do not trigger another request. Already geocoded addresses are protected by an address hash, and manually entered coordinates are not overwritten. Existing records are also not bulk-geocoded during installation.

Installation

bench get-app https://github.com/kgrininger/frappe_ots_geolocation
bench --site <site-name> install-app frappe_ots_geolocation

The app creates its custom fields during installation/migration but does not geocode existing Addresses as an installation task.

Configuration

The app reuses Frappe’s existing Geolocation Settings.

The basic setup is:

  1. Open Geolocation Settings
  2. Select a supported provider
  3. Configure the provider’s API key or Base URL
  4. Enable Auto-Vervollständigung Koordinaten if automatic geocoding is wanted

Frappe’s existing Enable Address Autocompletion setting and this app’s coordinate completion setting are intentionally separate:

  • Address Autocompletion helps the user enter an address.
  • OTS Geolocation geocodes a saved Address and writes coordinates to Address.location.

Providers

The app currently contains adapters for:

  • Geoapify
  • HERE
  • Nominatim, using Frappe v16’s provider option spelled Nomatim

Again, my own practical testing so far has primarily been with Geoapify.

For Nominatim, the app does not automatically select a public Nominatim server. The site operator needs to configure a Base URL and is responsible for provider policies, rate limits and usage terms.

Manual geocoding

A saved Address can also be geocoded manually from the form using:

Koordinaten abrufen

The configured provider is called synchronously and the result is written to Address.location.

An existing manual location is protected, and an unchanged already-geocoded address is not requested again.

API

There is also a permission-checked API for other Frappe apps:

from frappe_ots_geolocation.api import enqueue_geocode_addressresult = enqueue_geocode_address("ADDR-00001")

The same operation is available via Frappe RPC/REST.

The function checks that the current Frappe user has write permission on the Address. It does not elevate or bypass permissions. Automatic processing is queued after transaction commit on Frappe’s default queue.

Why I built it

I originally built OTS Geolocation for my own service application, OneTokenSite.

For the service platform I wanted to display open service cases on a map and later use location data for things like service planning and field-service workflows.

The first idea was to simply store coordinates on the relevant service objects. But while working through the data model, it became clear that this would duplicate information that really belongs to the address.

The cleaner approach was:

Customer / Contact / other DocType
        ↓
Frappe Address
        ↓
Address.location
        ↓
Map / routing / service planning

Once we had moved to that model, the actual geocoding functionality was no longer specific to OneTokenSite at all.

It only needed:

  • standard Frappe Address
  • standard Geolocation Settings
  • a configured geocoding provider
  • and Address.location

So I decided to extract it from the service application and publish it as a small standalone Frappe app.

My own use case is still service management — for example, showing open service cases geographically — but there is intentionally no dependency on OneTokenSite or ERPNext. The app only depends on Frappe.

Repository:

MIT licensed.

I would be very interested in feedback from the Frappe community, especially around:

  • testing HERE or Nominatim in real installations,
  • compatibility with other Frappe v16 setups,
  • different countries and address formats,
  • other providers worth supporting,
  • use cases outside of field service,
  • and whether there are existing Frappe conventions around Address.location that I may have missed.

Since this is a first v1, feedback and contributions are very welcome.Hello,