Welcome to the documentation of the Geomatic's geokoder. Here you will find the following:
- An overall non-technical description of how is it working.
- Description of how to use the API for the Geomatic's geokoder.
- Finally a full description of match codes that gives information about how well a match went.
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:
vars— a comma-seperated list of ids of variables that should be returned in the output. If this is not supplied, all available variables are returned. If you for instance only want the (Danish) variables conzoom type and conzoom group in the response, then appendvars=cnztyp_g5,cnzgrp_g5to the URL. We recommend always specifying the variables you need in thevarsargument, rather than leaving it out.cat— specifies how values of category variables are returned in the JSON output.catcan be set to the following values:id(default) — returns the ID of the category as a string value.obj— returns the full category object as the value.
-
coords— specifies how values of point variables are returned in the JSON output.coordscan be set to the following values:xy(default) — returns the coordinates in the local UTM zone with an X and Y part.latlong— returns the coordinates as latitude and longitude pairs using WGS84.
-
match_vars— Lets you specify which match variables you want to be returned in the match response. This argument can be set to:main(default) — returns the main variables, which includes generic match variables and any detailed match variables, but not match information variablesall— return all match variables.
match_on— If your matcher has the ability to match on multiple domains, and you only are interested in matching on a specific domain, then you can supply the ID of that domain as amatch_onargument. E.g. if you only want to match on access addresses when using the Swedish Geocoder , then appendmatch_on=acadrto the query string.
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 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 |
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 |