Download the PHP package clesson-de/silverstripe-geocoding without Composer

silverstripe-geocoding

Geocoding, reverse geocoding and routing for Silverstripe CMS 6.1, backed by OpenStreetMap (Nominatim / OSRM) and Google Maps.

Features

• Geocoding — resolve a postal address to geographic coordinates (latitude / longitude)
• Reverse geocoding — resolve coordinates back to a postal address
• Routing — calculate a driving route from an origin through optional waypoints to a destination
• Two built-in service backends — OpenStreetMap (free, no API key required) and Google Maps
• Address model — standalone address records with international formatting via commerceguys/addressing
• AddressType model — configurable address type taxonomy (e.g. invoice address, delivery address)
• Region dropdown API — AJAX endpoint for dynamic region/state dropdowns based on the selected country
• Automatic geocoding — Address records are geocoded automatically after each write (via AddressExtension)
• SiteConfig tab — manage geocoding service records directly from the CMS Settings panel
• Custom DBGeoCoordinate composite field — store latitude + longitude in a single $db declaration
• Rate limiting — configurable per-service delay between API requests (required by Nominatim's usage policy)

Requirements

Installation

After installation, run a database build:

Address and AddressType models

This module provides two standalone models for address management that can be used independently of — or in combination with — the clesson-de/silverstripe-contacts module.

Address

Represents a physical address. Fields: Name, AddressLine1, AddressLine2, PostalCode, City, Region, CountryCode.

A formatted Summary string (localised using commerceguys/addressing) is generated automatically onBeforeWrite. An interactive map field showing the geocoded coordinates is added via AddressExtension.

AddressType

A configurable taxonomy for address types (e.g. invoice address, delivery address). Default types can be seeded in project config:

Region dropdown API

When displaying an Address edit form, the region field uses a dynamic dropdown. The module exposes a JSON endpoint that returns subdivision options for a given country:

Requires CMS_ACCESS permission.

Configuration

Managing geocoding services in the CMS

1. Log in to the CMS.
2. Navigate to Settings (SiteConfig).
3. Open the Geocoding tab.
4. Select a map display service — choose which service provider (Google or OpenStreetMap) should render interactive maps in the CMS.
5. Add geocoding services for each method (geocode, reverse geocode, route):
   • Use the Add button to link existing services or Add new to create a service inline.
   • Set the Quota (maximum calls per day; 0 = unlimited).
   • Drag services to change their priority order — the first service with available quota is used.
6. Save the Settings page.

Creating a new geocoding service

1. In the Geocoding tab, click Add new under any method section.
2. Choose the service type: OpenStreetMap service or Google service.
3. Fill in the form:
   • Name — a descriptive label for this service record.
   • Active — enables or disables the service.
   • API key — required for Google Maps only.
   • Base URL — overrides the default Nominatim URL (OpenStreetMap only; leave empty to use the public API).
   • OSRM base URL — overrides the default OSRM routing URL (OpenStreetMap only).
   • Rate limit (ms) — minimum wait time in milliseconds between two requests. Set to at least 1100 for Nominatim to comply with the Nominatim usage policy.
4. Save the service.

User guide

Interactive map field

When editing an Address record in the CMS, you'll see an interactive map that displays the current coordinates (if set) and allows you to update them by clicking on the map:

• Marker — appears if coordinates are already set. Drag the marker to update the coordinates.
• Double-click — double-click anywhere on the map to place or move the marker.
• Single-click — single-clicks allow you to pan the map without accidentally moving the marker.
• Service — the map provider (Google Maps or OpenStreetMap) is determined by the Map display service setting in SiteConfig → Geocoding.

Frontend assets

This module includes JavaScript and CSS assets for the interactive map field. After installation, run:

This exposes the compiled assets from client/admin/dist/ to public/_resources/silverstripe-geocoding/.

Developing frontend assets

If you need to modify the JavaScript or SCSS:

1. Navigate to the module directory:

2. Install Node.js dependencies (using the version specified in .nvmrc):

3. Build the assets:

4. Or watch for changes during development:

The .nvmrc file specifies the required Node.js version (22). Use nvm to switch to the correct version automatically.

Troubleshooting

Map shows as grey box / tiles don't load initially

Symptom: When you open a form with a MapField (especially in GridField detail forms or tabs), you see a grey box. After reloading the page, the map tiles load correctly.

Cause: The map container is loaded via AJAX, but the JavaScript initialization ran before the container appeared in the DOM.

Solution: This is automatically handled by the Entwine integration (map-entwine.js). Make sure you have:

1. ✅ Run composer vendor-expose after installation
2. ✅ Cleared the Silverstripe cache (?flush=all)
3. ✅ Hard-refreshed your browser (Ctrl+Shift+R / Cmd+Shift+R)
4. ✅ Checked the browser console for JavaScript errors

How it works: The module uses jQuery Entwine to watch for .geocoding-map-container elements. When a container appears in the DOM (including via AJAX), Entwine automatically initializes the map after a short delay (100ms) to ensure all assets are loaded.

Debug: Open the browser console and check:

See Asset loading documentation for detailed debugging instructions.

Map doesn't appear at all

✓ Checklist:

• [ ] Map display service selected in Settings → Geocoding?
• [ ] Service is marked as Active?
• [ ] API key configured (for Google Maps)?
• [ ] composer vendor-expose executed?
• [ ] Browser console shows no JavaScript errors?

Coordinates don't save

✓ Checklist:

• [ ] Field name matches DB field name (e.g. 'GeoCoordinates')?
• [ ] Hidden input fields are present in the DOM?
• [ ] Form submitted successfully (check for validation errors)?

Coordinates are rounded / have fewer decimal places

Symptom: When you copy coordinates from Google Maps (e.g. 48.65129546574825, 9.28476328298257), they are saved with only 7 decimal places (e.g. 48.6512955, 9.2847633).

This is normal and intentional. The database uses DECIMAL(10,7) which provides 7 decimal places = ~1.1 cm accuracy. This is the industry standard for GPS coordinates and more than sufficient for address geocoding.

Google's 14+ decimal places (sub-micrometer precision) are only relevant for scientific/surveying applications. The difference is invisible on maps and has zero practical impact.

See the Coordinate precision guide for detailed explanation.

Developer documentation

Extensibility

This module is designed to be modular and extensible. You can add support for additional map providers (e.g. Bing Maps, Mapbox, HERE Maps) in your own module without modifying the core geocoding module.

How it works:

Documentation:

• Adding custom map providers guide — Step-by-step tutorial
• Provider best practices — Guidelines for high-quality implementations
• Architecture overview — Technical documentation of the provider system

Using DBGeoCoordinate in your own DataObjects

Declare the field in $db using the GeoCoordinate type alias:

This creates two database columns: LocationLatitude DECIMAL(10,7) and LocationLongitude DECIMAL(10,7).

Note on precision: The 7 decimal places provide ~1.1 cm accuracy, which is the industry standard for GPS coordinates and more than sufficient for address geocoding. Services like Google Maps may return coordinates with 14+ decimal places, but the additional precision (sub-micrometer) is only relevant for scientific/surveying applications and will be automatically rounded when saved.

Add the MapField to your getCMSFields():

Access the coordinate via the composite field object:

Using the service classes in code

Retrieve a configured service record and instantiate the matching service class:

Geocoding (address → coordinates)

Reverse geocoding (coordinates → address)

Routing (start + waypoints + destination → route)

License

BSD 3-Clause License — see LICENSE.