# Location Geo: Technical

# Introduction

The LocalGov Geo module provides an Geo Entity type, for storing descriptive and geographic data about locations. By default there is a bundle for addresses, with a point; and areas, with a polygon. The module provides a geo content administration page, and entity browser widget for creating and reusing locations in content.

# Permissions

There are permissions to administer Geo Entities; and permissions to view, add, edit and remove them. At this time there aren't per bundle permissions.

If installed as part of LocalGov Drupal distribution editors have permission to view, add, edit and remove them.

# Installation

The module is included in the LocalGov Drupal distribution. It is a depenency, and used with, modules such as Directories and Events. You can add it to other content types by configuring an entity reference field, see below.

# Configuration

# Geocoder

One important feature of the module is the ability to lookup addresses, autocomplete them, and find their location. Out of the box the module is configured to use OpenStreetMap Nominatim (opens new window). Its very reasonable Terms of Service (opens new window) allow us to make limited queries without requiring you to do more configuration, like registering an API key, so it works for testing. The data is the very flexible Open Data Commons Open Database Licensed (opens new window).

# Why doesn't it find...

In the UK however at the moment OpenStreetMap does lack some information you might expect, like a lot of house numbers for example - contributing to OpenStreetMap helps this. Nominatim as a free service does also only accept a limited number of queries. Because of both these reasons you want to configure another geocoder for use on your production site.

Ordnance Survey offers Councils access (opens new window) to its Places API (opens new window), or GIS departments might well have their preferred systems for your region.

LocalGov Geo uses the Drupal Geocoder module (opens new window) which in turn uses the Geocoder PHP Library (opens new window). This supports a wide range of geocoder providers (opens new window) and offers a straightforward way to add more. While some configuration might be different, the process is much the same for all Geocoders, usually authentication by token or oAuth.

# Example: ArcGIS Online

# Set up an App on ArcGIS Online

To be allowed to store Geocode results you will need a paid account with permission to do so. You then create an 'oAuth 2.0' app. Logging into you ArcGIS account you will see something like:

ArcGIS Online add auth 2.0 app

The app has a Client ID, and a Client secret. It also has a temporary token. You don't need this as Drupal Geocoder will generate them when required.

# Install the ArcGIS Online provider

First add the ArcGIS provider. You can find the providers list (opens new window) and Packagist (opens new window) basic installation instructions are also on them. These have related plugins (opens new window) to make them 'automagically' with geocoder.

So for ArcGIS: composer require geocoder-php/arcgis-online-provider

# Configure the ArcGIS Plugin

Visit Home > Administration > Configuration > System > Geocoder configuration > Geocoder providers and add a new gecoder. You should now see your new gecoder in the list.

NOTE: If you don't see your new plugin immediately after clearing caches there's an autoloader caching bug (opens new window) - you could try the patch, restart apache, or install another module, they will all make it appear.

Select the Arc GIS Online Token plugin

The Arc GIS Online Token plugin (patch) (opens new window) is the provider that permits you to store geocoder results. Once you have added the new provider plugin you will get the configuration page

Input the user name and password you got from ArcGIS

# Configure LocalGov Geo to use your new provider

Which geocoders are used can be found at Administration > Structure > Geo Type > Address > Manage form display. Configure the form address element to use the new Geocoder. You can have more than one geocoder, and order them if you want.

Address field autocomplete widget settings with Arc GIS Online Token enabled

# Add a location to a content type

To the content type an existing localgov_location entity reference field.

Administration > Structure > Content Types > content type > Manage Fields > Add field dialogue

This field can then be configured to reference Addresses and/or Areas.

Field settings dialogue selecting just address bundle

To get the full power of the location field you should use the 'Geo Entity Browser'.

Switch to 'Entity Browser' widget.

Drop down selecting the Entity Browser for the widget for Location field

Select the cog (right) to change the settings and save:

Entity Browser settings open for Location field

# Upgrading