Welcome to the documentation of the CPR Direkte matcher. 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 CPR Direkte matcher.
- Finally a full description of match codes that gives information about how well a match went.
How is it working?
Geomatic's CPR matcher allows you to look up persons in the Danish CPR registry. It works by calling CPR's own CPR Direkte webservice. For further details about what data is available and why you would use this API instead of the CPR Direkte webservice read here.
Using CPR Direkte matcher API
The API for CPR Direkte matcher follows the standard API for matchers.
To find a match using CPR Direkte matcher, you need to make a GET request that looks as follows:
As explained in the general documentation you pass the input to the CPR Direkte matcher in as the
in_* query string parameters. For CPR Direkte matcher you can use the following
||CPR number||The CPR number of the person supplied in the format DDMMYY-XXXX or DDMMYYXXXX.|
||Name||This argument must contain the name of the person.|
||Date of birth||The date of birth of the person supplied in the format DDMMYY.|
||Tele person id||The ID of a person from teledata.|
||Kvhx||Use this argument if you have the kvhx or kvh. If you supply this, then you can omit the other arguments.|
||Kommune code||If used, this argument must contain the kommune code.|
||Street code||If used, this argument must contain the street code.|
||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.|
||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.|
||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.|
||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.|
||Post code / City||If used, This argument must contain the post code and/or postaldistrikt/town/city name.|
||Apartment||If used, this argument should contain floor, apartment number and/or door specifier.|
Allowed Combinations of Input Arguments
Due to limitations in the CPR Direkte webservice, you have to use one of the following combiniations of inputs when matching:
- Personnummer (CPR number) — supply a value for
- Name and date of birth — supply a value for
- Name and address — supply a value for
in_nameand a combinitation of the address input fields, where there is at least, street, house number and postcode. You do not need to provide floor, suite or door number, but it might in some cases be required for a match.
Optional parameters specific for the CPR matcher
name_match— Lets you specify whether to try alternative forms of the provided name if the first one fails to match a person. This argument can be set to:
exact(default) — matches using the name as provided.
alt_names— matches first using the provided name, and if that fails it will try alternative names (based on the provided name).
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_g5to the URL. We recommend always specifying the variables you need in the
varsargument, 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 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_onargument. E.g. if you only want to match on access addresses when using the Swedish Geocoder , then append
match_on=acadrto the query string.
The structure of match response is described here in the general documentation. For specific examples, see the example section below.
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.
The following example will try to match on name Ole Stinson and address Vestervang 9 st 0053, 8000 Aarhus C:
https://apps.conzoom.eu/api/v1/match/dk/cpr?in_name=Ole Stinson&in_adr=Vestervang 9 st 0053, 8000 Aarhus C&vars=per_cpr_status,per_name,unadr_name
The following example will try to match on name Luther Stinson and address Vestervang 9 st 0053, 8000 Aarhus C, but there is no person with that name on the address.
https://apps.conzoom.eu/api/v1/match/dk/cpr?in_name=Luther Stinson&in_adr=Vestervang 9 st 0053, 8000 Aarhus C&vars=per_cpr_status,per_name,unadr_name
In order to tell how good a match was, or the reason why no match was found, the CPR Direkte matcher 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 CPR Direkte matcher. It would for most scenerios suffice to use this.
||CPR Not Available|
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.