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 (Danish: enhedsadresser) and access addresses (Danish: adgangsadresser) 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
Adgangsadresser	acadr	En adgangsadresse er ikke en postadresse. Den kan fx bruges til at identificerer en opgang eller en bygning ud fra husnummeret og husbogstavet. I DAR kaldes en adgangsadresse for et "Husnummer".
Enhedsadresser	unadr	En enhedsadresse er en adresse der kan sendes post til. Den kan fx identificerer en lejlighed i en opgang via etage og sidedør. I DAR kaldes en enhedsadresse blot for en "Adresse".
Postnummerveje	pcstreet	Det stykke af en vej som løber inden for det samme postnummer. For de fleste veje ligger hele vejen inden for det samme postnummer, men nogle veje strækker sig over flere postnumre, og vil således være opdelt i flere postnummerveje.

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.

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/dk/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_kvhx	Kvhx	Use this argument if you have the kvhx or kvh. If you supply this, then you can omit the other arguments.
in_muni	Kommune code	If used, this argument must contain the kommune code.
in_strcode	Street code	If used, this argument must contain the street code.
in_stednavn	Stednavn	Stednavn is a town name that is used as part of a Danish address, when the street name of an address appears in multiple towns within the same post code.
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_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_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.
in_pcode	Post code / City	If used, This argument must contain the post code and/or postaldistrikt/town/city name.
in_apt	Apartment	If used, this argument should contain floor, apartment number and/or door specifier.

If you have the entire address text in a single string, then it would suffice to use in_adr. Otherwise use the more specific in_* arguments above to supply the address you want to match.

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 append vars=cnztyp_g5,cnzgrp_g5 to the URL. We recommend always specifying the variables you need in the vars argument, rather than leaving it out.
• cat — specifies how values of category variables are returned in the JSON output. cat can 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. coords can 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 variables
  • all — 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 a match_on argument. E.g. if you only want to match on access addresses when using the Swedish Geocoder , then append match_on=acadr to 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

The following example will try to match the address Vestergade 20 1, 8700:

https://apps.conzoom.eu/api/v1/match/dk/geocoder?in_adr=Vestergade 20 1, 8700

In this example the geocoder tries to look up an address by using a DAWA KVHX key:

https://apps.conzoom.eu/api/v1/match/dk/geocoder?in_kvhx=02176821_131__2__th

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.

Detaljeret matchkode for enhedsadresse - unadr_matchlvl_detail

ID	Name	Description
im	Ingen match	Inputtet kunne på ingen måde matches
ia	Ingen adresse	Input kunne ikke genkendes som en adresse
ud	Udenlandsk	Adressen var udenlandsk og kunne derfor ikke matches
po	Postdistrikt	Postdistriktet kunne matches, men vejen kunne ikke findes i input
ve	Vej	Vejen kunne matches, men de angivne husnummer kunne ikke findes på vejen
hn	Husnummerdel, forkert husbogstav	Der kunne findes en adgangsadresse med matchende nummerdel af husnummer, men bogstavet i husnummeret matchede ikke
a	Adgangsadresse	Der kunne findes en adgangsadresse der matchede, men der var ingen enhed på adgangsadressen som matchede input
e2	Enhedsadresse, ikke eksakt	Der blev fundet en unik matchende enhedsadresse, men enten indeholdte input en yderligere specifikation af enheden som ikke kunne findes, eller også manglede input en specifikation af dør/sidedør som ikke var nødvændig for unikt at identificere adressen
e1	Enhedsadresse	Der blev fundet en unik matchende enhedsadresse

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 for enhedsadresse - unadr_matchlvl

ID	Name	Description
i	Utilstrækkeligt input	Det tilgængelige input var ikke tilstrækkeligt til at identificere en gyldig enhedsadresse
x	Ingen match	Ingen enhedsadresse kunne matches ud fra input
m	Match	En unik enhedsadresse blev matchet ud fra input
a	Tilnærmet match	En unik enhedsadresse kunne ikke identificeres ud fra input, men blev matchet som nærmeste nabo

Generisk matchkode for adgangsadresse - acadr_matchlvl

ID	Name	Description
i	Utilstrækkeligt input	Det tilgængelige input var ikke tilstrækkeligt til at identificere en gyldig adgangsadresse
x	Ingen match	Ingen adgangsadresse kunne matches ud fra input
m	Match	En unik adgangssadresse blev matchet ud fra input
a	Tilnærmet match	En unik adgangsadresse kunne ikke identificeres ud fra input, men blev matchet som nærmeste nabo

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 for etage input - matchinfo_floor

ID	Name	Description
x1	Ikke forsøgt	Match på etage blev ikke forsøgt, fordi adgangsadressen ikke blev identificeret
x2	Ingen match	Der blev ikke fundet nogen etage, der matchede med etagen angivet i input
m5	Match, men forkert etage i input	Etage i input, stemmer ikke med etagen i kildedata. Enheden er alligevel unikt identificeret uden etageangivelsen
m4	Match, men ingen etage i ZAP	Etage findes i input, men der er ingen etage i ZAP. Enheden er alligevel unikt identificeret uden etageangivelsen
m3	Match, men etage mangler i input	Etage mangler i input, men enheden er alligevel unikt identificeret vha sidedør
m2	Match ved split af sidedør i input	Sidedørsbetegnelsen i input indeholder både etage og sidedørs angivelse slået sammen i samme ord, fx kan 102 i virkeligheden være 1 etage, sidedør 2
m1	Match	Etagen blev matchet mod kildedata

Matchinfo for sidedør input - matchinfo_suite

ID	Name	Description
x1	Ikke forsøgt	Match på sidedør blev ikke forsøgt, fordi adgangsadressen ikke blev identificeret
x2	Ingen match	Der blev ikke fundet noget enhed med sidedørsbetegnelse som kunne matches med input. Dette kan skyldes at adressen ikke optræder som en rigtig enhed i ZAP, som fx køkkenet på et et kollegium
d2	Delvist match, eneste enhed på adgangsadressen	Adgangsadresse med en enkelt enhed er matchet, men etage/sidedørsbetegnelse i input kunne ikke matches med den for enheden. Dette forkommer ofte når en adgangsadresse som kun består af en enkelt enhed, er opdelt i flere lejemål som ikke er rigtige BBR enheder
d1	Delvist match, eneste enhed på etagen	Etage med en enkelt enhed er matchet, men sidedørsbetegnelse i input kunne ikke matches. Dette kan opstå når inputadressen i virkeligheden referer til en forbrugsadresse som fx køkkenet på et kollegium som ikke er en rigtig BBR enhedsadresse. Dette kan også skyldes at to lejligheder er lagt sammen
m5	Match, men en del af sidedørsangivelsen er taget bort	Match, men en del af sidedørsangivelsen er taget bort
m4	Match, husnummerforveksling	Adressen er matchet på enhedsniveau. Sidedørsbetegelsen eller en del deraf, er i input blevet forvekslet med husnummerbogstavet
m3	Match ved split af sidedør i input	Adressen er matchet på enhedsniveau. Sidedørsbetegnelsen i input indeholder både etage og sidedørs angivelse slået sammen i samme ord, fx kan 102 i virkeligheden være 1 etage, sidedør 2
m2	Match - alternativ betegnelse	Adressen er matchet på enhedsniveau, men der er afvigelser i måden sidedøren er skrevet på som fx tal i stedet for tv, th
m1	Match	Adressen er matchet på enhedsniveau. Sidedørsbetegnelse i input matcher en enhed i ZAP. Der kan være mindre forskellige i skrivemåden, så som foranstillede nuller ved lejlighedsnumre

Matchinfo for vejnavn input - matchinfo_strname

ID	Name	Description
x1	Ingen match	Input vejnavnet matcher ikke noget vejnavn indenfor det angivne postdistrikt, eller et unikt vejnavn
x2	Tvetydigt match	Der blev fundet to eller flere veje, hvor input adressen matchede ligegodt. Forekommer ved manglende stednavn i input
m4	Match på gammelt vejnavn	Vejnavnet matcher et gammelt CPR vejnavn fra vejen. Vejnavnet bør opdateres til det nye navn
m3	Match - ikke eksakt	Vejnavnet i input matcher CPR vejnavnet, men er ikke stavet som i CPR
m2	Match på vejkode	Vejen blev matchet ved brug af kommune- og vejkode
m1	Match	Vejnavnet i input matcher eksakt CPR vejnavnet

Matchinfo for husnummer input - matchinfo_houno

ID	Name	Description
x1	Ikke forsøgt	Match på husnummer blev ikke forsøgt, fordi vejen ikke blev identificeret
x2	Ingen husnummer i input	Input indeholder ikke noget husnummer for denne adresse
x3	Husnummeret er ikke fundet	Der er ikke fundet en adressen på vejen med samme husnummerdel som angivet i input
d1	Delvis match - husbogstav ikke fundet	Husbogstavet findes i input, men der ikke fundet en adresse med matchende husbogstav. Nummerdelen er matchet korrekt
d2	Delvis match - mangler påkrævet husbogstav	Husbogstav er påkrævet for dette husnummer, men der var intet husbogstav i input. Nummerdelen er matchet korrekt
m4	Match, forkert husbogstav	Enheden er unikt idenficeret ud fra etage/sidedør, men husnummer bogstav er forkert i input
m3	Match, manglende husbogstav	Enheden er unikt idenficeret ud fra etage/sidedør, men husbogstavet mangler i input
m2	Match, sidedørsforveksling	Match, men sidedørsbetegnelse er forvekslet med husbogstav i input
m1	Match	Eksakt match på husnummer (inkl husbogstav)

Matchinfo for postnummer input - matchinfo_pcode

ID	Name	Description
x1	Ingen match	Der kunne ikke findes noget postdistrikt med den i input angivne postnummer
x2	Ingen postkode	Input indeholder ikke postnummer
m4	Match, forkert postnummer	Adressen blev matchet, men postnummeret er forkert angivet i input
m3	Gammel postnummer	Postnummeret blev matchet mod en gammel postnummer for adressen. Postcode bør opdateres
m2	Match på kommune/vejkode	Postnummeret blev fundet ved opslag på kommune- og vejkode
m1	Match	Postnummeret er korrekt angivet i input

Matchinfo for postdistrikt input - matchinfo_postdist

ID	Name	Description
x1	Ingen match	Der kunne ikke findes noget postdistrikt som matcher med postdistriktsnavnet i input
x2	Ingen postdistriktsnavn i input	Input indeholder ikke et postdistriktsnavn
m5	Match, forkert postdistrikt	Adressen blev fundet, men postdistriktet er forkert angivet i input
m4	Gammel postdistrikt	Postdistrikt blev matchet mod et gammel postdistrikt for adressen. Postdistrikt bør opdateres
m3	Match ikke eksakt	Postdistrikt er matchet men ikke stavet rigtigt i input
m2	Match på kommune/vejkode	Postdistrikt blev fundet ved opslag på kommune- og vejkode
m1	Match	Postdistrikt er korrekt angivet i input