Du er ikke logget på
Geomatic's geokoder

Welcome to the documentation of the Geomatic's geokoder. Here you will find the following:

How is it working?

By geocoding is normally understood the process of finding geographic coordinates from postal address information. Geomatic's geocoder does a lot more than that. It also validates an address and is also able to find individual flats within a building.

Unit Address vs. Access Address

The difference between unit addresses (Swedish: bostadsadresser) and access addresses (Swedish: belägenhetsadresser) is important in order to understand how the geocoder works.

The unit address is the specific unit where a household can reside, where as the access address is only identifying the access to a building or staircase.

The access address is usually identified by the housenumber on a street. But if there are more flats for the same access address (house number), then a flat number is needed to identify the particular unit address (the flat). For one family houses, where there are no flats within the house, the unit address and the access address represents the same thing.

Matching

Geomatic's geokoder matches on the following domains:

Domain ID Description
Belägenhetsadresser acadr En belägenhetsadress anger var en plats finns. För bostadsadresser är det vanligen entrén eller infarten som adresseras.
Bostadsadresser unadr Med bostadsadress avses en adress som i flerbostadshus anges med lägenhetsnummer och får småhus och radhus anges som belägenhetsadress. Syftet är att så exakt som möjligt kunna matcha mot ett hushåll.
Postnummer pcode

It will attempt to return a match on the most specific domain, i.e. unit address, but if unsuccessful it will look for a match among access addresses. If no acceess address can be found it will return just the matching postcode.

The matching algorithm will handle incorrect spelling and typos in the address input in order to find a match. See examples of this in the examples section below.

Using Geomatic's geokoder API

The API for Geomatic's geokoder follows the standard API for matchers.

The Request

To find a match using Geomatic's geokoder, you need to make a GET request that looks as follows:

https://apps.conzoom.eu/api/v1/match/se/geocoder?in_x1=?&in_x2=?...

Input Arguments

As explained in the general documentation you pass the input to the Geomatic's geokoder in as the in_* query string parameters. For Geomatic's geokoder you can use the following in_* parameters:

Parameter Name Description
in_adr Address Use this argument if you have the entire address as a single text string. If you supply this, then you can omit the other arguments.
in_apt Apartment If used, this argument should contain floor, apartment number and/or door specifier.
in_houno House number If used, this argument must contain house number and/or letter. The argument can also handle floor/apartment number if this comes after the house number.
in_pcode Post code / City If used, This argument must contain the post code and/or postaldistrikt/town/city name.
in_str Street If used, this argument must contain the street name. The street name can optionally be followed by housenumber/letter and floor/apartment number, but these can also be supplied as seperate arguments if desired.

If you have the entire address text in a single string, then it would suffice to use in_adr as follows.

https://apps.conzoom.eu/api/v1/match/se/geocoder?in_adr={address}

Otherwise use the more specific in_* arguments above to supply the address you want to match. For example:

https://apps.conzoom.eu/api/v1/match/se/geocoder?in_str={street}&in_hou={housenumber}&in_pcode={postcode}

Optional parameters

You can add the following optional arguments as query string parameters:

The Response

The structure of match response is described here in the general documentation. For specific examples, see the example section below.

Batching

If you need to do multiple match requests, you can batch them using a batch request. This works in a very similiar way to the single match request.

Examples

Unit Address vs Access Address

The following is a match on a unit address in a building with flats. Here the flat number is needed to get a match on unit address.

https://apps.conzoom.eu/api/v1/match/se/geocoder?in_adr=Bergsgatan 24, lgh 1204, 21422 Malmö

Performing the same match but leaving out the flat number, will only give a match on access address:

https://apps.conzoom.eu/api/v1/match/se/geocoder?in_adr=Bergsgatan 24, 21422 Malmö

If the flat number does not exists, the the match wil>l also only be on access address

https://apps.conzoom.eu/api/v1/match/se/geocoder?in_adr=Bergsgatan 24, lgh 1084, 21422 Malmö 

Finally, matching an address with a house with no flats, will still give a unit address match.

https://apps.conzoom.eu/api/v1/match/se/geocoder?in_adr=Elevvägen 10, 61336

Approximate Matches

If the housenumber that is being searched does not exist in our address data, then we will try to return the nearest housenumber that exists. In the following example we search for house number 24, but finds 22. Note, how the match codes reflect that the match is not exact, but approximate.

https://apps.conzoom.eu/api/v1/match/se/geocoder?in_adr=Elevvägen 24, 61336

Handling Incorrect Input

Sometims the input you possess may not be complete or correctly spelled, the geocoder will still attempt to find a match, and as long a unique match can be found, then it will return this.

So the following misspelled streetname will still match, but the match info code will reflect that the street name was not spelt correctly.

https://apps.conzoom.eu/api/v1/match/se/geocoder?in_adr=Elevvag 10, 61336

In the following incorrect postcode and incorrectly spelled postort name is also fixed.

https://apps.conzoom.eu/api/v1/match/se/geocoder?in_adr=Elevvägen 10, 61333 Oxelosund, 61336

Match Variables

In order to tell how good a match was, or the reason why no match was found, the Geomatic's geokoder returns the match variables.

A match variable outputs a category, which tells something about how good a match was. Below you can see the categories for the different match variables. Normally you only need to use one of them, unless you are investigating why a particular input is not matching as expected.

Detailed Match Variable

The detailed match variable is defined specifically for the Geomatic's geokoder. It would for most scenerios suffice to use this.

Detaljerad matchkode för bostadsadress - unadr_matchlvl_detail

ID Name Description
x Ej match Input-datan kunde inte på något sätt matchas till en giltig bostadsadress
po Postort En postort men inget postnummer kunde matchas från input-datan
pc Postnummer Ett postnummer men ingen gatuadress kunde matchas från input-datan
st Gata En gata men inget giltigt husnummer kunde matchas
nn Närmsta granne Husnumret i input-datan kunde inte hittas, men ett husnummer hittades som närmsta granne. Närmsta granne hittas genom närmsta husnummer på samma gatsida, alternativt genom närmsta numeriska husnummer
aa Belägenhetsadress Husnumret i input-datan kunde matchas, men den specificerade bostadsadressen kunde inte hittas
ua Bostadsadress En bostadsadress kunde matchas

Generic Match Variables

The generic match variables has some common categories that are shared among different matchers. These are useful if you are programming generically against different matchers, and want a common way of handling matches.

There is a generic match variable for each domain that is being matched. Therefore, these variables can be useful to inspect if you interested in matches on a particular domain.

Generisk matchkode för bostadsadress - unadr_matchlvl

ID Name Description
i Ofullständig input Input-datan är inte tillräcklig för att identifiera en giltig bostadsadress
x Ej match Ingen bostadsadress kunde matchas från input-datat
m Match En unik bostadsadress var matchad från input-datan

Generisk matchkode för belägenhetsadress - acadr_matchlvl

ID Name Description
i Ofullständig input Input-datat innehåller inte tillräcklig information för att kunna identifiera en giltig belägenhetsadress
x Ej match Ingen belägenhetsadress kunde matchas utifrån input-datat
m Match En unik belägenhetsadress kunde matchas
a Ungefärlig match En belägenhetsadress i input-datat kunde inte matchas, men var identiferad som "närmsta granne". Närmsta granne hittas genom närmsta husnummer på samma gatsida, alternativt genom närmsta numeriska husnummer.

Generisk matchkode för postnummer - pcode_matchlvl

ID Name Description
i Ofullständig input Input-datat innehåller inte tillräcklig information för att kunna identfiera ett giltigt postnummer
x Ej match Inget postnummer kunde matchas från input-data
m Match Ett unikt postnummer kunde matchas från input-datat

Match Information Variables

The match information variables provide information about how well different parts of the input matched. These are mostly useful for debugging purposes, and are by default not returned in the output.

Matchinfo för lägenhet input - matchinfo_aptnm

ID Name Description
x0 Ej specificerat Input-datat innerhållet inget lägenhetsnummer
x1 Ej försökt Match på lägenhetsnummer försöktes ej då ingen belägenhetsadress kunde matchas
x2 Ej match Lägenhetsnumret i input-datat matchar inte lägenhetsnumret på den matchade adressen
m2 Ofullständig match Lägenheten i inputdatat matchar delvis lägenheten på den matchade adressen
m1 Match Lägenhetsnumret i input-datat matchar lägenhetsnumret på den matchade adressen

Matchinfo för gatunummer input - matchinfo_houno

ID Name Description
x0 Ej specificerat Input-datat innehåller inget husnummer
x1 Ej försökt Match på husnummer försöktes ej, då ingen gata kunde matchas
x2 Ej match Husnummret i input-datan kunde inte matchas med husnummer på den matchade gatan
m2 Ofullständig match Husnumret i inputdatat matchar delvis husnumret på den matchade adressen
m1 Match Husnumret i input-datan matchar husnumret på den matchade adressen

Matchinfo för gatunamn input - matchinfo_strname

ID Name Description
x0 Ej specificerat Input-datat innehåller inget gatunamn
x1 Ej försökt Match på gatunamn försöktes ej, då inget postnummer kunde matchas
x2 Ej match Gatunamnet i input-datat matchar inte gatunamnet på den matchade adressen
m2 Match men felstavat Gatunamnet i input-datat matchar delar av gatunamnet på den matchade adressen men är felstavat
m1 Match Gatunamnet i input-datat matchar gatunamnet på den matchade adressen

Matchinfo för postnummer input - matchinfo_pcode

ID Name Description
x0 Ej specificerat Input-datat innerhållet inget postnummer
x1 Ej försökt Match på postnummer i input-datat försöktes ej
x2 Ej match Postnumret i input-datat matchar inte postnumret på den matchade adressen
m1 Match Postnumret i input-datat matchar postnumret på den matchade adressen

Matchinfo för postort input - matchinfo_postort

ID Name Description
x0 Ej specificerat Input-datat innerhållet ingen postort
x1 Ej försökt Match på postort i input-datat försöktes ej
x2 Ej match Postorten i input-datat matchar inte postorten på den matchade adressen
m2 Match men felstavat Postorten i input-datat matchar delvis postorten på den matchade adressen men är felstavad
m1 Match Postorten i input-datat matchar postorten på den matchade adressen