Address API — Validate a single address (REST)

Support DQE
Support DQE
  • Updated

Use the /single/ endpoint to return address suggestions from a single free-form address input. Once the user selects an address, optionally call /compl/ to retrieve building or apartment complement details.

GET request

Endpoint

https://{SERVER_ADDRESS}/{VERSION}/single/?Address={INPUT}&Length={LENGTH}&Country={COUNTRY_CODE}&Licence={LICENCE_CODE}&Limit={NB}&Version=1&Langue={LANGUAGE}&Filter={FILTER}

Replace the values in braces with your own information.

Parameter Value Description Mandatory/Optional
SERVER_ADDRESS {SERVER_ADDRESS} Address of the DQE server that will process the data. Mandatory
VERSION {VERSION} Version of the API (e.g. v1). Mandatory
Licence {LICENCE_CODE} Licence code assigned to your account or token generated by oauth2. Mandatory
Address {INPUT} User input. Mandatory
Country {COUNTRY_CODE} ISO 3-letter country code. Mandatory
Length {LENGTH} Character limit for the address. Works only on Latin addresses. Optional. Default: 38. Recommended minimum: 32.
Limit {NB} Limits the number of returned responses. Maximum: 20. Optional. Default: 20.
Version 1 Allows the street type to be returned in the response. Optional
Langue {LANGUAGE} For Japan only: JP Kanji, JK Katakana, EN English. Optional
Filter {FILTER} France only. 1: all addresses. 2: no Cedex. 3: Cedex only. Optional

POST request

Endpoint

https://{SERVER_ADDRESS}/{VERSION}/single/

Add the parameters below in the request body using x-www-form-urlencoded.

Parameter Value Description Mandatory/Optional
Licence {LICENCE_CODE} Licence code assigned to your account or token generated by oauth2. Mandatory
Address {INPUT} User input. Mandatory
Country {COUNTRY_CODE} ISO 3-letter country code. Mandatory
Length {LENGTH} Character limit for the address. Optional. Default: 38. Recommended minimum: 32.
Limit {NB} Limits the number of returned responses. Maximum: 20. Optional. Default: 20.
Version 1 Allows the street type to be returned in the response. Optional
Langue {LANGUAGE} For Japan only: JP Kanji, JK Katakana, EN English. Optional
Filter {FILTER} France only. 1: all; 2: no Cedex; 3: Cedex only. Optional

Response

Success response

The JSON response contains a Found count and an Addresses array. Each element contains one address suggestion.

{
  "Found": 2,
  "Addresses": [
    {
      "PostalCode": "75008",
      "City": "Paris 8e Arrondissement",
      "Hamlet": "",
      "SpecialDistribution": "",
      "Country": "FRA",
      "StateCode": "75",
      "SubLocality": "",
      "CityId": "75056",
      "Input": "12 AV DES CHAMPS ELYSEES",
      "Label": "12 Av des Champs-Elysees 75008 Paris 8e Arrondissement",
      "AdditionalAddress": "",
      "StreetNumber": "12",
      "StreetType": "Av",
      "Street": "des Champs-Elysees",
      "StreetId": "750080153",
      "IsValidStreetNumber": true,
      "StreetNumberListCount": 148,
      "StreetNumberList": "1,3,5,...",
      "StreetNumberOnly": "12",
      "StateLabel": "Paris",
      "AdministrativeArea": "Ile-de-France",
      "Suburb": "",
      "Company": "",
      "Latitude": null,
      "Longitude": null
    }
  ]
}
Key Description Size / Type
PostalCode Postal code of the address. String (up to 10 characters)
City City name. String (up to 100 characters)
Hamlet Hamlet or locality. Optional string
SpecialDistribution Special distribution mention. Optional string
Country ISO 3166-1 alpha-3 country code. Fixed string (3 characters)
StateCode State or administrative region code. Optional string
SubLocality Sub-locality or neighborhood. Optional string
CityId Internal identifier for the city. String or integer
Input Original user input. String (up to 255 characters)
Label Formatted address label. String (up to 255 characters)
AdditionalAddress Address complement. String (up to 255 characters)
StreetNumber Street number. String (up to 10 characters)
StreetType Street type. String (up to 50 characters)
Street Street name. String (up to 100 characters)
StreetId Unique street identifier. String
IsValidStreetNumber Street number validity indicator. Integer
StreetNumberListCount Number of available street numbers. Integer
StreetNumberList Available street numbers. String or array
StreetNumberOnly Street number without complement. Optional string
StateLabel Full state or region name. Optional string
AdministrativeArea Administrative subdivision above the city. Optional string
Suburb Suburb or district. Optional string
Company Company name associated with the address. Optional string
Latitude Latitude coordinate. String or number
Longitude Longitude coordinate. String or number

Error response

Errors are returned as JSON in the following format:

{
  "status": 401,
  "message": "Unauthorized",
  "details": "Invalid licence code",
  "error": "Unauthorized"
}
Error type Request Response type
Missing Licence parameter https://{SERVER_ADDRESS}/{VERSION}/single/?Address=UB96NS&Country=GBR {"status":400,"message":"Missing parameters","details":"Licence","error":"bad request"}
Empty Licence parameter https://{SERVER_ADDRESS}/{VERSION}/single/?Address=UB96NS&Country=GBR&Licence= {"status":400,"message":"Licence must be filled","details":"Empty","error":"bad request"}
Incorrect licence number https://{SERVER_ADDRESS}/{VERSION}/single/?Address=UB96NS&Country=GBR&Licence={WRONG_LICENSE} {"status":401,"message":"Your licence is not allowed to cover this functionality","details":"{WRONG_LICENSE}","error":"unauthorized_client"}
Missing Address parameter https://{SERVER_ADDRESS}/{VERSION}/single/?&Country=GBR&Licence={LICENSE} {"status":400,"message":"Missing parameters","details":"Address","error":"bad request"}
Missing Country parameter https://{SERVER_ADDRESS}/{VERSION}/single/?Address=a&Licence={LICENSE} {"status":400,"message":"Missing parameters","details":"Country","error":"bad request"}
Empty Country parameter https://{SERVER_ADDRESS}/{VERSION}/single/?Address=a&Country=&Licence={LICENSE} {"status":400,"message":"Country must be filled","details":"Empty","error":"bad request"}
Error on a parameter https://{SERVER_ADDRESS}/{VERSION}/single/?Adress=a&Country=GBR&Licence={LICENSE} {"status":400,"message":"Missing parameters","details":"Address","error":"bad request"}

Swagger documentation

See also

Was this article helpful?

0 out of 0 found this helpful