Geocoder

Introduction

Geocoding is the computational process of transforming a physical address description to a location on the Earth's surface (spatial representation in numerical coordinates). Reverse geocoding, on the other hand, converts geographic coordinates to a description of a location, usually the name of a place or an addressable location. Geocoding relies on a computer representation of address points, the street / road network, together with postal and administrative boundaries.

-- Wikipedia

The Geocoder API can be used to query addresses, Point Of Interests (POI) and stops. Its primary purpose is to find the start- and end points for queries to the journey planner API.

The following query will return a list of destination- or arrival points containing POI's, addresses and stops that match the string "sons":

An example of what it looks like in our journey planner:

Authentication

The Geocoder is open under NLOD licence, however, it is required that all consumers identify themselves by using the header ET-Client-Name. Entur will deploy strict rate-limiting policies on API-consumers who do not identify with a header and reserves the right to block unidentified consumers. The structure of ET-Client-Name should be: "company - application"

Header examples:

  • "brakar - journeyplanner"
  • "fosen_utvikling - infoplakat"
  • "norway_bussekspress - reiseplanlegger"

 

 

 

Geocoder API

The geocoder API is based on the open source product "Pelias". 

Examples

Find coordinates based on text

The base URL for the API is:

Here is an example which searches for places beginning with "aln", from a "focus point" (usually the geographic position of your device):

Find location based on coordinates

You can also use the geocoder to find places in the vicinity of a position. This is the reverse query:

In this example, we are looking for 1 address near a specific coordinate:

 

Documentation

You'll find official Pelias documentation on GitHub.

We have also added our own enhancements to support local- or technical needs:

Size

Governs the maximum number of results.

Parameter Valid values Example Methods
size [1-100] https://api-test.entur.org/api/geocoder/1.1/autocomplete?lang=no&text=ha... autocomplete

 

Boundaries

Allows filtering by geographical region.

Parameter Valid values Example Methods
boundary.county_ids Comma separated list

Norwegian county numbers equal the first two digits in the municipality numbers:

https://api.entur.org/api/geocoder/1.1/autocomplete?lang=no&text=hald&bo...

autocomplete
boundary.county_ids Comma separated list

Norwegian municipality numbers are four digit numbers:

https://api.entur.org/api/geocoder/1.1/autocomplete?lang=no&text=hald&bo...

autocomplete

 

Tariff zones

Allows filtering stops by tariff zone.

Parameter Valid values Example Methods
tariff_zone_authorities Comma separated list https://api.entur.org/api/geocoder/1.1/autocomplete?lang=no&text=hald&ta... autocomplete
tariff_zone_ids Comma separated list https://api.entur.org/api/geocoder/1.1/autocomplete?lang=no&text=hald&ta... autocomplete

 

multiModal

Controls whether the search returns multimodal stops, child stops of the multimodal stops, or both. Does not affect monomodal stops.

Parameter Valid values Example Methods
size

parent (default)

child

all

Only multimodal stops without children:

https://api-test.entur.org/api/geocoder/1.1/autocomplete?lang=no&text=hald

 

Only child stops:

https://api.entur.org/api/geocoder/1.1/autocomplete?lang=no&text=hald&mu...

 

Both:

https://api.entur.org/api/geocoder/1.1/autocomplete?lang=no&text=hald&mu...

autocomplete

 

Definitions

Layers

Due to limitations in Pelias the definitions of layers has been re-defined and limited to the following two layers:

Layer Description
venue

Stops

address

POI, streets, addresses, stop groups

Categories

Used for subtyping within layers.

Layer Category Description
venue onstreetBus,
onstreetTram,
airport,
railStation,
metroStation,
busStation,
coachStation,
tramStation,
harbourPort,
ferryPort,
ferryStop,
liftStation,
vehicleRailInterchange,
other
Stops from NSR. On multimodal stops, these values are only found on their child stops.
address GroupOfStopPlaces Stop groupings from NSR.
address POI Collected from OpenStreetMap.
address Street address Addresses from 'Kartverket'.
address Street Street names from 'Kartverket'. Coordinate is the median address-location.
address Places Placenames from 'Kartverket'. Currently only 'tettsted' and 'bydel'. See https://www.kartverket.no/globalassets/standard/sosi-standarden-del-1-og... for fullstendig liste. for complete list of available places.

 

Counties and municipalities

Layer Category Example
county

Name of county (fylke)

Østfold
county_gid

ID of county (prefixed with "whosonfirst:county")

whosonfirst:county:01
locality

Name of municipality (kommune)

Oslo
locality_gid

ID of county (prefixed with "whosonfirst:locality")

whousonfirst:locality:0301