Geocoding application end-user documentation


The Geocoding application is being developed by AVINET, a Norwegian technology company specialized in development of Web Based map solutions and spatial data infrastructures. This software has been developed as part of the LoCloud project, Best Practice Network with participation from 30 different European countries part-funded by the European Commission.

This user manual includes simple instructions on how to use the LoCloud Geocoding Microservice.

Good luck with your geocoding projects

(Stein) Runar Bergheim
Co-founder & Senior Advisor, AVINET Ltd

Terms and concepts

  • Geocoding: the process of manually or automatically assigning locations to an existing source that has a spatial component such as a reference point, an address or a georgraphical name
  • Data source: A table, uploaded by the user that can be geocoded.
  • Search database: An existing authoritative source of locations, i.e. Geonames
  • Area: an area of the user interface, i.e. header, right margin, main content, left margin
  • Panel: a collapsible section placed inside a user interface area
  • Item: A collective term for row, record or object from a data source table
  • Attribute: a property, field, column, value associated with an item.

Overview of the user interface

The following are the main components of the user interface. The screen is divided into seven areas. Some of these are further subdivided into collapsible sections called panels. The areas and panels are as follows:

  • The header area contains a logo and the site title
  • The top menu area contains menu buttons for navigation, information, download of data - and for logging out
  • The left margin area is located on the left side of the screen
    • The settings panel contains a slider that permits us to set the default zoom
    • The data source panel contains functions to select and filter data sources to be geocoded
  • The map area occupies the upper part of the main content area
  • The ''geocoding form' occupies the lower part of the main content area
  • The view and edit attribute form is a modal window that can be activated from the geocoding form
  • The right margin area is located on the right side of the screen
    • The search panel contains fields to select a database, to limit the search and to enter a search expression
    • The useful location sources panel allows you to open various external applications zoomed in on the same area to see if they contain hints as to where your item is located.

Step by step instructions

This section of the manual contains step by step instructions on how to perform a geocoding task.


Register new user


Manage users

Working with data sources

Creating a new data source

In order to do geocoding, you first have to upload a file that you would like to add coordinates to. This is a very simple procedure that involves selecting a CSV file from your computer and specifying some simple metadata.

  1. Create a CSV (comma separated variables) file with the information that you would like to geocode. If your application cannot export such a file directly, you can easily create one using Microsoft Excel by choosing, File --> Save as... and choose "Comma Separated Variables" as file type.
  2. Open the geocoding application and log in with your user account
  3. Choose the menu option "New datasource..."
  4. Select the file you'd like to upload using the "Select file..." dialog
  5. Select which column in the table (if any) that contains the:
    1. unique ID of the dataset (mandatory)
    2. name of the item (mandatory)
    3. category item (optional)
    4. 1st level area division (optional)
    5. 2nd level area division (optional)
    6. existing X-coordinate column (optional)
    7. existing Y-coordinate column (optional)
    8. spatial reference system code
      1. The default coordinate system is WGS1984 geographical coordinates, specified by the keyword (EPSG:)4326, other coordinate systems can be specified. If your desired spatial reference system is not in the drop-down, you can request it to be added by contacting AVINET
      2. The value you select here must correspond to the spatial reference of existing coordinates, if you have any. If you have a data source without existing coordinates, you can specify any coordinate system here.
  6. Click the Upload file button
  7. If there are any error messages, please correct the issues highlighted and try again.

Manage data sources

Select and filter your data source

At this stage you have uploaded your data source and need to come to terms how the application user interface works. The first thing to understand is the data source panel.

The first element in the data source panel is a drop-down box that permits you to select which data source you want to work with.

  • To proceed, please select a data source from in the drop down box with the label Please select a source

When you select that data source, two additional drop-down boxes appears in the data source panel.

  1. Filter by areas
  2. Filter by category

In addition there was already one drop-down box in place: Filter by probability. The latter is better understood after going through the functions of the geocoding form.

These drop-down boxes will allow you to limit the types and number of elements that will be displayed in the paged list of items that appears on the bottom of the right margin area when you select a data source.

By paged we mean that not all items are shown in one tall list, rather each page contains ten items and Previous and Next buttons allow you to move between the pages.

Once you click on an item in the item list, the orange geocoding form appears at the lower part of the main content area.

Using the geocode form and the view/edit attributes form

Once you have clicked on an item from your selected data source you are now ready to update the location and attributes of the item.

The geocoding form contains four editable elements:

  1. The editable field Name of item
  2. The editable field X-coordinate (or Longitude)
  3. The editable field Y-coordinate (or Latitude)
  4. The selectable button set Probability (1=certain)
    • The value 1 indicates that the user is 100% certain of the location of the item
    • The value 2 indicates that the user is 90% certain
    • The value 3 indicates that the user is 50% certain
    • The value error is used when an item is encountered that is simply wrong (i.e. duplicates etc.)

In addition, the geocoding form contains five buttons

  • A View all attributes button that opens the View/edit attributes form as a popup.
  • A View link button that appears if the data source contains a URL field opens an external link as a separate browser window.
  • A View image button that appears if the data source contains an image URL field displays the image in a popup window.
  • A Cancel button that closes the geocoding form discarding any changes
  • A Save button that saves any changes made in the form.
    • Please note that when you press the Save button, an indicator icon appears in front of the item name in the item list.
    • The icon uses the traffic light paradigm where the color corresponds to the probability value set in the form where:
      1. = green light
      2. = yellow light
      3. = red light
    • records marked as error are displayed with a prohibition sign icon in front of the item name.

Add coordinates to an item

There are two ways you can add coordinates to the currently selected item:

  1. You can click in the map and the coordinates will be transferred to the fields - this is easy
  2. You can manually edit the content of the fields if you for an example have collected GPS-coordinates - this is accurate but cumbersome

The first option is the one we are going to emphasize in this instruction manual.

View and edit source item attributes

The geocoding form only allows you to view and edit three attributes. If you want to see all the attributes that exist for an item you must use the View all attributes button. This will produce the View/edit source attributes form

This form is laid out as a table with three columns:

  1. The first column contains the names of the attribute (or field)
  2. The second column contains the original value of the attribute
  3. The third column is empty but enable users to enter an alternative values into the form

Once a user has made changes to an items attributes he or she can choose to save them by clicking the Save attribute edits button or discard them by clicking the Close without saving button.

Either way, the data are not updated in the database until the user clicks Save in the Geocoding form.

For those who are technically disposed, the modified data are stored as a JSON object in the gc_fieldchanges attribute of the match table.

How to use the map

The map is really very simple. It is a tile-based map client similar to Google Maps built on the excellent, albeit similarly bulky, OpenLayers library.

The advantage with this library is that it supports literally any GIS requirement known to man kind. The drawback is that it is a bit large as a download: i.e. >= 700 Kb. This is not so nice in an end-user application (although it is the same as Google Maps) but it is quite ok for a professional application like the Geocoding Application.

The benefit of using this (or Leaflet as is the case in the web map solution in your portal) is that they permit you to use other base map data sources than Google. You can mix and match between Open Street Map, Cloud Made, Bing, Yahoo, Here, Google and more. You can even connect your own WMS servers.

The map only support some very simple functions - you can't go wrong.

  • Click and hold the mouse button while you drag the mouse to move around in the map - this is called panning in the GIS world. Learn it now and you won't have to later.
  • Use the + button on the upper left to zoom in one step
  • You can also zoom in one step by double-clicking in the map
  • Use the - button second from the top on the left to zoom out one step
  • If you wish to zoom to a specific area, you can hold the shift button and the left mouse button simultaneously and drag a rectangle around the area you'd like to zoom in on
  • Single click to place the selected item and update the X- and Y-coordinate fields

You can switch between different background maps by selecting the + button on the upper right side of the map. Only one base layer can be visible at the same time.

Using search databases

So, you have the data source, you have the map but you're unable to find the location you're looking for.

The Geocoding microservice contains a search panel at the right margin area of the user interface. Here you can presently choose to search in the Geonames database to see if the place you are looking for exists in the source.

  1. Select a database using the Please select a database drop-down box in the Search panel.
    • At present, it only makes sense to choose Geonames as this is the only data source that covers your area
  2. Choose whether you want to limit the search to search results within the visible portion of the map
    • This can be useful if you are working with a common name that occurs many places but you know roughly where an item is located.
  3. Enter a name or a partial name into the search field between the drop-down box and the within map check box and press search.
  4. A search result list appears at the bottom of the screen
  5. Select elements from the search result list to zoom and recenter the map on the respective search result
  6. Now, use the map navigation functions to move around and single-click in the map to mark the correct location of your item

Using external applications

Some times you will not be able to find the location of an object you would like to geocode simply by browsing the map. Don't worry. The world's biggest database of information is right in front of you: the Internet.

Be careful though, it is very easy to put information on the Internet and for this reason it is also very easy to put something wrong on Internet.

However, in order to help you with your geocoding work, we have integrated a number of mainstream map applications and made it possible to open them showing the same area as the one you are currently working in. These include:

  • Google Maps (best in terms of completeness)
  • Nokia Here (best in terms of accuracy)
  • Wikimapia (best in terms of things you can't find anywhere else)
  • Geonames (a global source of names)
  • Google Search (when nothing else works)

Whenever you click on the button with the name of one of these sources, a new browser window will open. The center of the map will be the same as the center of the map you have in the Geocoding application. The zoom level will usually be different.

By querying these external applications, you will be able to find the locations of many things that are otherwise impossible to locate.

In some instances, the only solution is to visit the site and log the location with your GPS or Smartphone. However, due to the geocoding application being deployed as a SaaS application, it is also possible to ask someone with local knowledge to update the location of certain features - if in doubt.

Downloading augmented data

So, you've reached the end of the geocoding project and you would like to take download the augmented data to put them back into your system.

You do like this:

  1. Select the data source you would like to export in the drop-down box in the left-margin area of the main user interface.
  2. Click one of the download buttons in the top menu and save the file to your computer; you can choose between
    • CSV (the most basic format for working with any data source)
    • JSON (popular for many contemporary web applications)
    • KML (for viewing the data in Google Earth - or for loading into many GIS applications)
    • RDF (for loading into a graph database