Address API - Check and verify an address (RESTful)

Support DQE

Updated 11 August 2026 11:47

Validation - RESTful

Validates and normalises a complete address. Returns a corrected address, a deliverability verdict (DQEDetailCode), and optionally a breakdown of which fields were adjusted.

When to call this endpoint - CheckAddress is the Level 2 validation step. Trigger it when the user types an address freehand or modifies a DQE suggestion before submitting. If the user accepted a DQE suggestion as-is, quality is already guaranteed - no call needed.

Request

Both GET and POST are supported.

{SERVER_ADDRESS}, {VERSION} and {LICENCE_CODE} are provided by DQE upon account creation. Contact your DQE account manager to obtain these credentials.

Address input must be URL-encoded - e.g. l'église → l%27%C3%A9glise.

GET POST

GEThttps://{SERVER_ADDRESS}/{VERSION}/checkaddress/?Address={INPUT}&Country={COUNTRY_CODE}&Licence={LICENCE_CODE}

cURL examples

France - with Modification=O and Version=1.1

curl "https://{SERVER_ADDRESS}/v1/checkaddress/?Address=%7C1%20rue%20de%20la%20louisiane%7C%7C31200%7Ctoulouse&Country=FRA&Length=38&Modification=O&Version=1.1&Licence={LICENCE_CODE}"

International - Italy

curl "https://{SERVER_ADDRESS}/v1/checkaddress/?Address=%7CSTRADA%20BARDONEY%7C%7C11028%7CVALTOURNENCHE&Country=ITA&Length=38&Licence={LICENCE_CODE}"

POSThttps://{SERVER_ADDRESS}/{VERSION}/checkaddress/

Send all parameters in the request body using Content-Type: application/x-www-form-urlencoded. The server address remains in the URL.

cURL example

France - full address with Modification flag

curl -X POST "https://{SERVER_ADDRESS}/v1/checkaddress/" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "Address=%7C1+rue+de+la+louisiane%7C%7C31200%7Ctoulouse" \
  -d "Country=FRA" \
  -d "Length=38" \
  -d "Modification=O" \
  -d "Version=1.1" \
  -d "Licence={LICENCE_CODE}"

Parameters

Parameter	Value	Description	Mand / Opt
Licence	`{LICENCE_CODE}`	Your DQE licence key or OAuth2 token. Contact support if you do not yet have one.	Mandatory
Address	`{INPUT}`	Pipe-separated address string. All five pipes are mandatory even when fields are empty. For France, a sixth segment can be prepended for the delivery point (apartment, floor, mailbox). additional address\|address\|dependent locality or state\|zip code\|city Example: `\|1 rue de la louisiane\|\|31200\|toulouse`	Mandatory
Country	`{COUNTRY_CODE}`	ISO 3166-1 alpha-3 country code for the address search scope. Example: `FRA` or `GBR`.	Mandatory
Length	`{LENGTH}`	Character limit for the `Address` response field. Applies to Latin-character addresses only. Default: `38`. Recommended minimum: `32`.	Optional
Suggestion	`{PROP}`	France only. Controls how correction results are returned. `O` - Record `"1"` contains the standard correction result. If the address cannot be uniquely matched, additional suggestions are returned as records `"2"` to `"n"`. `S` - Record `"1"` returns the input address as-is with its validation status (not corrected). If a clear correction is found, it is returned as record `"2"`. Automatically enables `Modification=O`.	Optional
Modification	`O`	Fixed value `O`. Populates `ChangedAddressTag` and `IsAddressChanged` in the response, indicating which address fields were adjusted (additional address, address, dependent locality, zip code, or city). See ChangedAddressTag.	Optional
Version	`{VERSION}`	`1.1` - Populates geocoding quality fields (`LatLonLabel`, `LatLonCode`) in the response (France only, subscription required - contact your DQE account manager to enable).	Optional

Response fields

The response is a JSON object with two top-level keys: Found (integer) and Addresses (array of address objects). When Suggestion=O, multiple address objects may be returned.

Complement fields - Validation applies up to the street number. When a complement is submitted (building name, floor, etc.) and matches a referenced complement, the engine enriches it with the full registered name. When no complement is submitted, the full list of available complements is returned (semicolon-separated). Unrecognised complements are returned as-is.

Output casing - The casing follows the postal norm of the country concerned.

Top-level

Key	Description	Type
Found	Number of address objects returned.	Integer
Addresses	Array of address objects.	Array

Address object - `Addresses[0]`

Key	Description	France	International
Address	Normalised address line (street number, type and name).	String (38)	String (50)
PostalCode	Postal code.	String (5)	String (10)
City	City name.	String (38)	String (50)
Hamlet	Named locality or hamlet (France) or equivalent district-level field (international). Availability varies by country.	String (38)	String (50)
SpecialDistribution	CEDEX indicator: `1` = CEDEX address, `0` = not CEDEX.	String (1)	String (1)
Country	ISO 3166-1 alpha-3 country code.	String (3)	String (3)
StateCode	State or administrative region ISO code.	Always `"*"`	String (50)
SubLocality	Sub-locality.	Empty	String (50)
CityId	Unique city identifier (INSEE code for France).	String (20)	String (20)
Input	Not populated for this endpoint. Always returns an empty string.	String	String
Label	Formatted display label for the address. Not returned for all international datasets.	String	String
AdditionalAddress	Additional address information (building name, floor, etc.).	String (1024)	String (150)
StreetNumber	Full street number including any complement (bis, ter, etc.).	String (10)	String (10)
StreetType	Street type (e.g., `RUE`, `AVENUE`, `BOULEVARD`).	String (20)	String (20)
Street	Street name without number or type.	String (38)	String (50)
StreetId	Unique street identifier.	String (20)	String (20)
IsValidStreetNumber	Street number validity indicator. `1` if the number exists in the reference data, `0` otherwise. Returns an empty string for some international addresses where number-level validation is not available.	Integer	Integer
StreetNumberListCount	When the queried number is not found or missing, returns the total count of valid street numbers for this street. Can be an empty string for some international addresses where this data is not available.	String	String
StreetNumberList	Semicolon-separated list of all valid numbers on this street. Populated when the submitted number is invalid or absent.	String (1024)	String (1024)
StreetNumberOnly	Street number only, without any complement (bis, ter, etc.).	String (10)	String (10)
StateLabel	State or region label.	Not available	String
AdministrativeArea	County or equivalent administrative level.	Empty	String
Suburb	Suburb.	Empty	String
Company	Company name associated with the address.	String (38)	String (38)
Latitude	Geocoordinates of the matched address. Not available for all countries - see coverage.	String	String
Longitude	Geocoordinates of the matched address. Not available for all countries - see coverage.	String	String
Informations	DQE validation metadata object. See below.	Object	Object

Informations object - `Addresses[0].Informations`

Key	Description	France	International
DQEDetailCode	Validation result code. See DQEDetailCode below.	String (2)	String (2)
DQEErrorAddressLabel	Plain-text validation result label (`OK` or an error description).	String (38)	String (38)
AdditionalAddressComp	Additional information from address line 2.	String (38)	String (38)
StreetNumberComp	Street number complement (bis, ter, etc.).	String (38)	String (50)
StreetNumberId	Unique street number identifier (Hexaclé for France).	String (10)	Not available
PostalCityId	Postal city identifier (Hexaposte code for France).	String (6)	Not available
IrisCode	IRIS statistical unit code. France only, subscription required - contact your DQE account manager to enable.	String (9)	Not available
RoudisCode	Roudis routing code. France only.	String (5)	Not available
LatLonLabel	Geocoding quality label (e.g., `ENTREE`, `BATIMENT`). Populated when `Version=1.1`. See Geocoding quality.	String	Not available
LatLonCode	Geocoding quality numeric code. Populated when `Version=1.1`.	String	Not available
IsAddressChanged	`1` if at least one field was adjusted, `0` otherwise. Always present in the response.	String (1)	String (1)
ChangedAddressTag	5-character binary string indicating which address fields were adjusted. See ChangedAddressTag. Always present; populated when `Modification=O` is set.	String (5)	String (5)

Populated when Version=1.1 Populated when Modification=O

Response example

1 Rue de la Louisiane 31200 Toulouse

{
  "Found": 1,
  "Addresses": [
    {
      "Address":              "1 RUE DE LA LOUISIANE",
      "PostalCode":           "31200",
      "City":                 "TOULOUSE",
      "Hamlet":               "",
      "SpecialDistribution":  "",
      "Country":              "FRA",
      "StateCode":            "*",
      "SubLocality":          "",
      "CityId":               "31555",
      "Input":                "",
      "Label":                "",
      "AdditionalAddress":    "BATIMENT D RESIDENCE ALLEE DES CEDRES;BATIMENT A RESIDENCE ALLEE DES CEDRES;BATIMENT B RESIDENCE ALLEE DES CEDRES;BATIMENT C RESIDENCE ALLEE DES CEDRES",
      "StreetNumber":         "",
      "StreetType":           "RUE",
      "Street":               "DE LA LOUISIANE",
      "StreetId":             "2408474",
      "IsValidStreetNumber":  "",
      "StreetNumberListCount":"",
      "StreetNumberList":     "",
      "StreetNumberOnly":     "1",
      "StateLabel":           "",
      "AdministrativeArea":   "",
      "Suburb":               "",
      "Company":              "",
      "Latitude":             "43.634746",
      "Longitude":            "1.430098",
      "Informations": {
        "DQEDetailCode":        "10",
        "DQEErrorAddressLabel": "OK",
        "AdditionalAddressComp":"",
        "StreetNumberComp":     "",
        "StreetNumberId":       "3155526YEA",
        "PostalCityId":         "14411",
        "IrisCode":             "3701",
        "RoudisCode":           "4221",
        "LatLonLabel":          "",
        "LatLonCode":           "",
        "IsAddressChanged":     "1",
        "ChangedAddressTag":    "" }
    }
  ]
}

DQEDetailCode

Addresses[0].Informations.DQEDetailCode is the primary validation result indicator. Use it to determine the action to take after form submission.
For recommended UI messages associated with each code, refer to the Integration Guide.

Code	Description
10	Correct address
20	Correct address (street not recognized, but it is a CEDEX or P.O. box)
21	Small town, street number out of range
22	Small town, street number missing (the rest of the address is correct)
23	Large city, street number out of range
24	Large city, street number missing (the rest of the address is correct)
25	CEDEX address unknown to CEDEXA (if CEDEXA is active)
30	Small town, street not recognized
31	Small town - street not recognised or missing; district info recognised but insufficient to determine the street. France only.
40	Not expected in current cloud deployments. Defined for compatibility.
41	Small town, street missing
50	Large city, street not recognized
51	Large city, street not recognised or missing (district information recognised but insufficient to determine the street). France only.
60	Not expected in current cloud deployments. Defined for compatibility.
61	Large city, street missing
70	Postal code / city mismatch - street present
71	Not expected in current cloud deployments. Defined for compatibility.
80	Postal code / city mismatch - street missing
81	Input address block empty. Not returned for France.
90	International address detected - the input country code does not seem to match the input address.
95	Missing or incorrect country code

Small vs Large city - In France, a city is considered Large when it has more than 2 500 inhabitants. Internationally, the threshold is 500 streets. This distinction determines whether small-town codes (21, 22, 30, 31, 41) or large-city codes (23, 24, 50, 51, 61) apply.

District - Codes 31 and 51 indicate that a district was recognised: a geographic zone identified by the engine (e.g. a hamlet or housing estate) that cannot be matched to a specific street. These codes are France only.

DQEDetailCode - input examples

Sample inputs that produce each code. Fields not listed are left empty.

Code	France	International
10	`\|20 rue Jean-Baptiste Pigalle\|\|75009\|Paris`	`Albert Buildings\|3 Scott Drive\|\|WA15 8AB\|ALTRINCHAM` GBR
20	`\|RUE DES FRERES LUMIERE\|BP 30036\|33564\|CARBON BLANC`	-
21	`\|26 route du chardonnay\|\|24130\|Ginestet`	`\|Seulestraat 200\|\|8950\|Heuvelland` BEL
22	`\|route du chardonnay\|\|24130\|Ginestet`	`\|Seulestraat\|\|8950\|Heuvelland` BEL
23	`\|13 rue Jean-Baptiste Pigalle\|\|75009\|Paris`	`\|Rue Victor Hugo 235\|\|7012\|Mons` BEL
24	`\|rue Jean-Baptiste Pigalle\|\|75009\|Paris`	`\|Rue Victor Hugo\|\|7012\|Mons` BEL
25	`\|\|\|82016\|Montauban CEDEX`	-
30	`\|rue Jean-Baptiste Pigalle\|\|24130\|Ginestet`	`\|Via del lungo\|\|70011\|Alberobello` ITA
31	`\|SAINT SYMPHORIEN\|\|12490\|VIALA DU TARN`	Not returned outside of France
40	Not expected in current cloud deployments. Defined for compatibility.	Not expected in current cloud deployments. Defined for compatibility.
41	`\|\|\|24130\|Ginestet`	`\|\|\|70011\|Alberobello` ITA
50	`\|route du chardonnay\|\|75009\|Paris`	`\|STREET ABCD\|\|60607\|CHICAGO` USA
51	`\|Lotissement Casella\|\|20243\|PRUNELLI DI FIUMORBO`	Not returned outside of France
60	Not expected in current cloud deployments. Defined for compatibility.	Not expected in current cloud deployments. Defined for compatibility.
61	`\|\|\|75009\|Paris`	`\|\|\|60607\|CHICAGO` USA
70	`\|rue de la mairie\|\|75009\|Bordeaux`	`\|FRANKLIN GTWY SE\|\|00067\|MARIETTA` USA
71	Not expected in current cloud deployments. Defined for compatibility.	Not expected in current cloud deployments. Defined for compatibility.
80	`\|\|\|75009\|Bordeaux`	`\|\|\|00067\|MARIETTA` USA
81	Not returned for France	`\|\|\|\|`
90	`\|7C avenue Monbijou\|\|4960\|Malmedy` Country: FRA - address appears non-French	-
95	-	-

ChangedAddressTag

Populated when Modification=O is added to the request. IsAddressChanged is 1 if any field was adjusted, 0 otherwise. ChangedAddressTag is a 5-character binary string, one position per address field. 1 = adjusted by DQE, 0 = unchanged.

additional address|address|dependent locality|zip code|city

ChangedAddressTag	Meaning
`00000`	No fields adjusted - address accepted as submitted.
`11111`	All five fields adjusted.
`00011`	Zip code and city adjusted; other fields unchanged.
`01111`	Address, dependent locality, zip code and city adjusted; additional address unchanged.
`10000`	Only additional address adjusted.
`01000`	Only address line adjusted.
`00100`	Only dependent locality adjusted.

Tip - When IsAddressChanged is 1, at least one field was changed by DQE. Display the correction to the user as a popup, always preserving the option to keep their original input.

Geocoding quality

When Version=1.1 is set and geocoding is subscribed, two fields are populated inside the Informations object: LatLonLabel (label) and LatLonCode (numeric code). France only.

Code	LatLonLabel	Description
1	ENTREE	Main access point to an enclosure, building group, or land parcel (address plate).
2	BATIMENT	Building or part of a building.
3	ESCALIERS	Stairwell, normally inside a building.
4	LOGEMENT	Housing or room inside a building.
5	PARCELLE CADASTRALE	Cadastral parcel.
6	SEGMENT DE VOIE	Position derived from the connecting street segment. May be outside the city polygon but on the same street.
7	POINT D ACCESS TECHNIQUE	Technical access point (water, electricity, gas shut-off, etc.).
8	POINT DELIVRANCE POSTALE	Postal delivery point (mailbox).
9	ZONE D ADRESSAGE	Point placed in the dependent locality.
10	CENTRE VILLE	Centre of the city.
0	CENTRE DE LA VOIE	Point in the centre of the street.
90	A CONTROLER	Geocoding quality uncertain - to be checked.
99	NON PRESENTE	Geocoding not available for this address.

Errors

The RESTful endpoint returns a structured JSON error body with an HTTP status code, a message, and an error identifier.

HTTP	Error type	Response body
400	Missing `Licence` parameter	`{"status":400,"message":"Missing parameters","details":"Licence","error":"bad request"}`
400	Empty `Licence` parameter	`{"status":400,"message":"Licence must be filled","details":"Empty","error":"bad request"}`
401	Incorrect licence number	`{"status":401,"message":"Your licence is not allowed to cover this functionnality","details":"{WRONG}","error":"unauthorized_client"}`
400	Missing `Address` parameter	`{"status":400,"message":"Missing parameters","details":"Address","error":"bad request"}`
400	Missing `Country` parameter	`{"status":400,"message":"Missing parameters","details":"Country","error":"bad request"}`
400	Empty `Country` parameter	`{"status":400,"message":"Country must be filled","details":"Empty","error":"bad request"}`
400	Typo in parameter name	`{"status":400,"message":"Missing parameters","details":"Address","error":"bad request"}`

Test the API

Click the button below to test this endpoint live in your browser.

Open console

Address API - Check and verify an address (RESTful)

Request

cURL examples

cURL example

Parameters

Response fields

Top-level

Address object - `Addresses[0]`

Informations object - `Addresses[0].Informations`

Response example

DQEDetailCode

DQEDetailCode - input examples

ChangedAddressTag

Geocoding quality

Errors

Test the API

See also

Was this article helpful?

Previous article

Next article

Request

cURL examples

cURL example

Parameters

Response fields

Top-level

Address object - Addresses[0]

Informations object - Addresses[0].Informations

Response example

DQEDetailCode

DQEDetailCode - input examples

ChangedAddressTag

Geocoding quality

Errors

Test the API

See also

Was this article helpful?

Previous article

Next article

Address object - `Addresses[0]`

Informations object - `Addresses[0].Informations`