FieldtypeGeocoder by Neue Rituale

Retrieve, collect and store geolocation data from external geocoding services


What it does

Retrieve, collect and store geolocation data from external geocoding services. Under the hood, the module uses the great PHP Library geocoder-php by William Durand and Tobias Nyholm and adds some processwire magic. Thanks to Ryan (FieldtypeMapMarker) and mats (FieldtypeLeafletMapMarker), from which we drew a lot of inspiration developing this module!


  • Fulltext search in formatted Address
  • Proximity search
  • Search in geojson
  • Easily hookable geocoding providers (supported providers)
  • Normalized geocoder object from geocoder-php
  • Supports The GraphQL-Module by dadish


  1. Copy the files for this module to /site/modules/FieldtypeGeocoder/
  2. Execute the following command in the /site/modules/FieldtypeGeocoder/ directory.
    composer install
  3. In processwire admin: Modules > Refresh and install Fieldtype > Geocoder.
  4. Insert the api-key for your geocoding provider. The default provider is OpenCage. OpenCage uses various other geocoding services. You can change the provider with a processwire hook. read more
  5. Create a new field of type Geocoder, and name it whatever you like. In our examples we named it simply "geocoder".
  6. Add the field to a template and start geocoding!
  • For GraphQL install the moduel GraphQLFieldtypeGeocoder


  • PHP >= 7.3
  • PHP Extensions: json, curl, intl

Module Configuration

Modules > Configure > FieldtypeGeocoder

Insert you api key here. The default


Field Configuration

Fields > your_field > input

Each field can have a default map center


API Reference

Seach in input
// Fulltextsearch
Search in formatted address
// Fulltextsearch
Search in properties
// Simplesearch
Search and order by proximity
$pages->find('geocoder.proximity=52.473758|13.402580, limit=3');
Search by status
 * @see Geocoder::statusOn
 * @see Geocoder::statusSingleResult
 * @see Geocoder::statusMultipleResults
$pages->find('geocoder.status=3'); // Status "On" and "SingleResult"
$pages->find('geocoder.status&2|4'); // Status "SingleResult" or "MultipleResults"

The Geocoder Object

ProcessWire\Geocoder Object
    [data] => Array
            [status] => 5
            [formatted] => Berlin, Deutschland
            [query] => Berlin
            [geodata] => Array
                    [type] => Feature
                    [bounds] => Array
                            [east] => 13,5488599
                            [west] => 13,2288599
                            [north] => 52,6770365
                            [south] => 52,3570365

                    [geometry] => Array
                            [type] => Point
                            [coordinates] => Array
                                    [0] => 13,3888599
                                    [1] => 52,5170365


                    [properties] => Array
                            [country] => Deutschland
                            [locality] => Berlin
                            [timezone] => Europe/Berlin
                            [postalCode] => 10117
                            [providedBy] => opencage
                            [adminLevels] => Array
                                    [1] => Array
                                            [code] => BE
                                            [name] => Berlin
                                            [level] => 1


                            [countryCode] => DE


            [lat] => 52,517036
            [lng] => 13,38886
            [provider] => opencage


Hooks / Change provider

You can hook some methods to change or override the geocoding provider. Here you can find a full list of supported providers.

  1. Download, unzip provider package.
  2. Move the files in your folder structure (Provider.php and ProviderAddress.php)*.
  3. Load all files with require_once() command.

*Replace "Provider" with the provider name e.g. Google or Mapbox etc.

Example 1: Google Maps Provider Package

/** @global Wire $wire */
$wire->addHookBefore('FieldtypeGeocoder::getProvider', function(HookEvent $event) {

	require_once (/*NoCompile*/__DIR__ .'/providers/GoogleMaps.php');
	require_once (/*NoCompile*/__DIR__ .'/providers/GoogleAddress.php');

	$fieldtype = $event->object;
	$apiKey = $fieldtype->apiKey; // or insert the key direct
	$adapter = $event->argumentsByName('adapter');

	$event->return = new \Geocoder\Provider\GoogleMaps\GoogleMaps($adapter, null, $apiKey);
	$event->replace = true;

Example 2: Mapbox Search Provider Package

use Geocoder\Provider\Mapbox\Mapbox;
use Geocoder\Query\GeocodeQuery;
use Geocoder\Query\ReverseQuery;

/** @global Wire $wire */

$wire->addHookBefore('FieldtypeGeocoder::getProvider', function(HookEvent $event) {

	require_once (/*NoCompile*/__DIR__ .'/providers/Mapbox.php');
	require_once (/*NoCompile*/__DIR__ .'/providers/MapboxAddress.php');

	$fieldtype = $event->object;
	$adapter = $event->argumentsByName('adapter');

	$event->return = new Mapbox($adapter, $fieldtype->apiKey, null);
	$event->replace = true;

 * Manipulate the query
 * For better results, add all mapbox types to the query
$wire->addHookAfter('FieldtypeGeocoder::filterQuery', function(HookEvent $event) {

	/** @var GeocodeQuery|ReverseQuery $query */
	$query = $event->argumentsByName('query');
	$query = $query->withData('location_type', Mapbox::TYPES);
	$event->return = $query;


  • Update provider-string if you use the autocomplete function from the inputfield or move the marker.
  • Refactor the inputfield javascript for other maps or mapstyles
  • Add warnings if a vendor package is not found!
  • Add warning if api key is empty


If you have any feedback, please reach out to us at

Install and use modules at your own risk. Always have a site and database backup before installing new modules.

Twitter updates

    Error retrieving Twitter status

Latest news

  • ProcessWire Weekly #473
    In the 473rd issue of ProcessWire Weekly we'll check out latest core updates, introduce new third party module called Template Fragment Controller, and more. Read on! / 3 June 2023
  • A look at the new Page Edit Restore module
    The new Page Edit Restore module helps to prevent page edits in the admin from getting lost when the user’s session is lost. This post covers it in detail.
    Blog / 12 May 2023
  • Subscribe to weekly ProcessWire news

“We chose ProcessWire because of its excellent architecture, modular extensibility and the internal API. The CMS offers the necessary flexibility and performance for such a complex website like ProcessWire offers options that are only available for larger systems, such as Drupal, and allows a much slimmer development process.” —xport communication GmbH