Getting started

• Getting started
  • Introduction
    • Prerequisite:
    • Glossary
  • API description
    • Summary of ressources
    • Summary of operations
    • Details of each operation
      • operationId : normalizePortalAddress
        • Description
        • Securing the operation
        • Technical Parameters
        • Functional Parameters
      • Requests examples
        • Success case - without warning
        • Success case - Suggested Localities + Locality choice
        • Success case - Suggested streets + Street choice
        • Success case - with Warning - unrecognized term
        • Success case - with warning - street number not provided
        • Success case - with warning - Hexacle not provided
        • Error 400 - case - invalid locality
        • Error 400 - case - invalid postal code
        • Error 400 - case - invalid street name
        • Error 400 - Case - out of bounds street number
        • Case : Error 500
  • ### Document history

Introduction

Prerequisite:

normalizePostalAddress API requires a Bearer Token. To get this token, you need to follow instructions as described in Authorization part with client credentials flow.

Glossary

Term	Definition
hexacleNumber	SNA Code for de number in the street
hexacleStreet	SNA Code for the street
hexavia	Internal SNA Code for the street
SNA	"Service National de l'Adresse" : a french corporation which is a reference for French postal Adresses

Back to top

API description

Summary of ressources

Ressource	Definition
postal address	the postal address to normalize

 

Back to top

Summary of operations

There is only one operation available for postalAddress.

operation	verb	URL
normalizePostalAddress	POST	/customer-management/v1/postal-addresses/normalization

Back to top  

Details of each operation

operationId : normalizePortalAddress

Description

• This API allow to :

  • Correct and check an address according to a location validator repository
  • Normalize (with French Postal standard) an address
  • Suggest localities or streets name if datas request are ambiguous.

• The repository is updated monthly.

Securing the operation

• Secured with client credentials flow

normalizePostalAddress API requires a Bearer Token. To get this token, you need to follow instructions as described in Authorization part for client credentials flow.

Technical Parameters

Parameters	Definition
CONTENT-TYPE	application/json
AUTHORIZATION	Bearer Token => Mandatory
X-SOURCE	String allowing to identify explicitly the caller (ex: PARTNER_NAME)

Functional Parameters

Parameters	Definition
streetNumber	Number in the street (ex: "2" or "2 ter") String - Optional
streetName	Describe the street's name String - Optional
additionalInformation	Additional information String - Optional
postOfficeBox	Post Office Box String - Optional - Mandatory if the street name and the additionnal information are missing
postCode	Post Code String - Optional - Mandatory if locality is missing
locality	City Name String - Optional - Mandatory if the post code is missing
valSuggestion	Internal Key provided by a first request with answer of type suggestedLocalities or suggestedStreetNames. All others parameters must be unchanged for the second request String - Optional

Requests examples

Success case - without warning

In this example, we send a request with an addressing containing a streetName, additionalInformation, postCode and locality.

Request :

curl -X POST -d "{ \"streetNumber\":\"1\",\"streetName\":\"place de la paix\",\"additionalInformation":"appartement 114",\"postCode\":\"78190\",\"locality\":\"TRAPPES\"}" http://b-api-env-ap1.adb.dev.euw1.nbyt.fr/v1/customer-management/postal-addresses/normalization -H "Content-Type: application/json" -H "Authorization: Bearer at-ef003b10-01ec-402c-8719-d5313557df1a" -H "X-Source: PARTNER_NAME"

The API returns a simple response completing the address with hexacleNumber, hexacleStreet, hexavia and localityInseeCode.

It converts the previous address sent in body request in a standardized postal address. You can see for example that locality and streetName are in uppercases now.

Response :

HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8

{
    "normalizedPostalAddress": {
        "hexacleNumber": "78621229HX",
        "hexacleStreet": "78621229E9",
        "hexavia": "03803036",
        "locality": "TRAPPES",
        "localityInseeCode": "78621",
        "postCode": "78190",
        "streetName": "PLACE DE LA PAIX",
        "streetNumber": "1"
    }
}

Success case - Suggested Localities + Locality choice

• Normalization in 2 steps following an ambiguity about the city

In this example, we begin to send a first address but without locality but with postCode "35650".

Request 1 : Response contains a list of localities

curl -X POST -d "{ \"streetNumber\":\"8\",\"streetName\":\"ajoncs\",\"postCode\":\"35650\"}" http://b-api-env-ap1.adb.dev.euw1.nbyt.fr/v1/customer-management/postal-addresses/normalization -H "Content-Type: application/json" -H "Authorization: Bearer at-ef003b10-01ec-402c-8719-d5313557df1a" -H "X-Source: PARTNER_NAME"

The API returns a 200 response but without normalized postal address. Instead it returns a list of two suggested localities.

Response :

HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
{
    "suggestedLocalities": [
        {
            "coincidence": 95,
            "inseeCode": "35240",
            "locality": "LE RHEU",
            "maxPostCode": "35659",
            "minPostCode": "35650",
            "suggestedDispatchLocality": "LE RHEU",
            "suggestionNumber": 0,
            "valSuggestion": "015299--------00000095---------------------23811C**"
        },
        {
            "coincidence": 95,
            "inseeCode": "35910",
            "locality": "MOIGNE",
            "maxPostCode": "35650",
            "minPostCode": "35650",
            "suggestedDispatchLocality": "LE RHEU",
            "suggestionNumber": 1,
            "valSuggestion": "015300--------00000095---------------------23811C**"
        }
    ]
}

For getting a postal address, we need to send another request with the same body as before, except this time we will add a valSuggestion.

In this example, the address we are looking for is in Moigne locality so we add the value "015300--------00000095---------------------23811C" as valSuggestion.

Request 2 : The locality choice allow to validate address

curl -X POST -d "{ \"streetNumber\":\"8\",\"streetName\":\"ajoncs\",\"postCode\":\"35650\",\"valSuggestion\": \"015300--------00000095---------------------23811C**\"}" http://b-api-env-ap1.adb.dev.euw1.nbyt.fr/v1/customer-management/postal-addresses/normalization -H "Content-Type: application/json" -H "Authorization: Bearer at-ef003b10-01ec-402c-8719-d5313557df1a" -H "X-Source: PARTNER_NAME"

This second request returns a standardized postal address.

Response :

HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
{
    "normalizedPostalAddress":  {
        "hexacleNumber":  "35240223GU",
        "hexacleStreet":  "35240222AA",
        "hexavia":  "00675226",
        "locality":  "LE RHEU",
        "localityInseeCode":  "35240",
        "postCode":  "35650",
        "streetName":  "RUE DES AJONCS",
        "streetNumber":  "8"
    }
}

Success case - Suggested streets + Street choice

• Normalization in 2 steps following an ambiguity about the street

We send a request with an incomplete streetName "vauguirard".

Request 1 : Response contains a list of streets

curl -X POST -d "{ \"streetNumber\":\"500\",\"streetName\":\"vaugirard\",\"postCode\":\"75006\",\"locality\":\"paris\"}" http://b-api-env-ap1.adb.dev.euw1.nbyt.fr/v1/customer-management/postal-addresses/normalization -H "Content-Type: application/json" -H "Authorization: Bearer at-ef003b10-01ec-402c-8719-d5313557df1a" -H "X-Source: PARTNER_NAME"

The response returns a list of three suggested street names.

Response :

HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
{
    "suggestedStreetNames":  [
        {
            "coincidence":  96,
            "locality":  "PARIS",
            "postCode":  "75006",
            "streetName":  "RUE DE VAUGIRARD",
            "suggestionNumber":  0,
            "valSuggestion":  "012559--------00007100J00000---------------03357*S*"
        },
        {
            "coincidence":  96,
            "locality":  "PARIS",
            "postCode":  "75015",
            "streetName":  "RUE DE VAUGIRARD",
            "suggestionNumber":  1,
            "valSuggestion":  "012559--------00007100J00001---------------03357*S*"
        },
        {
            "coincidence":  96,
            "locality":  "PARIS",
            "postCode":  "75015",
            "streetName":  "BOULEVARD DE VAUGIRARD",
            "suggestionNumber":  2,
            "valSuggestion":  "012559--------00007100N0348004096----------03357*S*"
        }
    ]
}

We resend the first request but this time with the proper valSuggestion: in this case, we are looking for "BOULEVARD DE VAUGIRARD".

Request 2 : The street choice allow to validate address

curl -X POST -d "{ \"streetNumber\":\"500\",\"streetName\":\"vaugirard\",\"postCode\":\"75006\",\"locality\":\"paris\",\"valSuggestion\": \"012559--------00007100N0348004096----------03357*S*\"}" http://b-api-env-ap1.adb.dev.euw1.nbyt.fr/v1/customer-management/postal-addresses/normalization -H "Content-Type: application/json" -H "Authorization: Bearer at-ef003b10-01ec-402c-8719-d5313557df1a" -H "X-Source: PARTNER_NAME"

This second request returns a standardized postal address but with a warning "MISSING_HEXACLE_NUMBER": there is no hexacleNumber returned.

Response :

HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
{
    "normalizedPostalAddress":  {
    "hexacleStreet":  "75115222MH",
    "hexavia":  "01456466",
    "locality":  "PARIS",
    "localityInseeCode":  "75115",
    "postCode":  "75015",
    "streetName":  "BOULEVARD DE VAUGIRARD",
    "streetNumber":  "500"
},
"warning":  ["MISSING_HEXACLE_NUMBER"]
}

Success case - with Warning - unrecognized term

The case below shows a warning to inform that one or more terms have not been used to find the address.

We are looking for "13-15 avenue du maréchal juin" in "meudon-la-foret".

Request:

curl -X POST -d "{\"streetNumber\":\"13-15\",\"streetName\":\"avenue du maréchal juin\",\"additionalInformation\":\"technopole\",\"postCode\":\"92360\",\"locality\":\"meudon-la-foret\"}" http://b-api-env-ap1.adb.dev.euw1.nbyt.fr/v1/customer-management/postal-addresses/normalization -H "Content-Type: application/json" -H "Authorization: Bearer at-ef003b10-01ec-402c-8719-d5313557df1a" -H "X-Source: PARTNER_NAME"

In this example, the check is not able to recognize '13-15', it doesn't understand why there is two numbers and "-". The API only considers the first number "13".

The response returned is a warning: "UNRECOGNIZABLE_ITEM"

Response :

HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
{
    "normalizedPostalAddress":  {
        "hexacleNumber":  "9204822BAV",
        "hexacleStreet":  "92048222HI",
        "hexavia":  "01750446",
        "locality":  "MEUDON",
        "localityInseeCode":  "92048",
        "postCode":  "92360",
        "streetName":  "AVENUE DU MARECHAL JUIN",
        "streetNumber":  "13"
},
"warning":  ["UNRECOGNIZABLE_ITEM"]
}

Success case - with warning - street number not provided

The case below shows a warning indicating that the address is validated but that there are street numbers while none has been entered.

0 is not considered like a street number: we send a request with a "0" StreetNumber.

Request:

curl -X POST -d "{\"streetNumber\":\"0\",\"streetName\":\"route HLM LE HETRE\",\"additionalInformation\":\"APPARTEMENT 26\",\"postCode\":\"50400\",\"locality\":\"GRANVILLE\"}" http://b-api-env-ap1.adb.dev.euw1.nbyt.fr/v1/customer-management/postal-addresses/normalization -H "Content-Type: application/json" -H "Authorization: Bearer at-ef003b10-01ec-402c-8719-d5313557df1a" -H "X-Source: PARTNER_NAME"

The response returns a 200 but with two warnings : "MISSING_STREET_NUMBER" and "MISSING_HEXACLE_NUMBER".

Response :

HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
{
    "normalizedPostalAddress":  {
        "hexacleStreet":  "502182224X",
        "hexavia":  "00994797",
        "locality":  "GRANVILLE",
        "localityInseeCode":  "50218",
        "postCode":  "50400",
        "streetName":  "HLM LE HETRE"
    },
    "warning":  ["MISSING_STREET_NUMBER","MISSING_HEXACLE_NUMBER"]
}

Success case - with warning - Hexacle not provided

The case below shows a warning to inform that the number is not checked, the software cannot assign a hexacleNumber.

Request:

curl -X POST -d "{\"streetNumber\":\"54\",\"streetName\":\"avenue de varsovie\",\"postCode\":\"62300\",\"locality\":\"LENS\"}"
 http://b-api-env-ap1.adb.dev.euw1.nbyt.fr/v1/customer-management/postal-addresses/normalization -H "Content-Type: application/json" -H "Authorization: Bearer at-ef003b10-01ec-402c-8719-d5313557df1a" -H "X-Source: PARTNER_NAME"

Response :

HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
{
    "normalizedPostalAddress":  {
        "hexacleStreet":  "624982222M",
        "hexavia":  "01238211",
        "locality":  "LENS",
        "localityInseeCode":  "62498",
        "postCode":  "62300",
        "streetName":  "AVENUE DE VARSOVIE",
        "streetNumber":  "54"
    },
    "warning":  ["MISSING_HEXACLE_NUMBER"]
}

Error 400 - case - invalid locality

The case below shows a KO because the city is unknown from the repository.

Request :

curl -X POST -d "{\"streetNumber\":\"1\",\"streetName\":\"rue du poulpe rieur\",\"postCode\":\"35000\",\"locality\":\"r'lyeh\"}" http://b-api-env-ap1.adb.dev.euw1.nbyt.fr/v1/customer-management/postal-addresses/normalization
 -H "Content-Type: application/json" -H "Authorization: Bearer at-ef003b10-01ec-402c-8719-d5313557df1a" -H "X-Source: PARTNER_NAME"

Response :

HTTP/1.1 400 Bad Request
Content-Type: application/json; charset=UTF-8
{
    "error":  "INVALID_LOCALITY",
    "error_description":  "La localité n’existe pas"
}

Error 400 - case - invalid postal code

The case below shows a KO because the postal code is unknown from the repository.

Request :

curl -X POST -d "{\"streetNumber\":\"4\",\"streetName\":\"place de bretagne\",\"postCode\":\"35999\"}" http://b-api-env-ap1.adb.dev.euw1.nbyt.fr/v1/customer-management/postal-addresses/normalization -H "Content-Type: application/json" -H "Authorization: Bearer at-ef003b10-01ec-402c-8719-d5313557df1a" -H "X-Source: PARTNER_NAME"

Response :

HTTP/1.1 400 Bad Request
Content-Type: application/json; charset=UTF-8
{
    "error":  "INVALID_POST_CODE",
    "error_description":  "Le code postal n’existe pas"
}

Error 400 - case - invalid street name

The case below shows a KO because the street name is unknown from the repository.

Request :

curl -X POST -d "{\"postOfficeBox\":\"BP36388\",\"postCode\":\"44000\",\"locality\":\"NANTES CEDEX 2\"}" http://b-api-env-ap1.adb.dev.euw1.nbyt.fr/v1/customer-management/postal-addresses/normalization -H "Content-Type: application/json" -H "Authorization: Bearer at-ef003b10-01ec-402c-8719-d5313557df1a" -H "X-Source: PARTNER_NAME"

Response :

HTTP/1.1 400 Bad Request
Content-Type: application/json; charset=UTF-8
{
    "error":  "INVALID_STREET_NAME",
    "error_description":  "La voie n’existe pas"
}

Error 400 - Case - out of bounds street number

The case below shows a KO because the street number is on a street shared between several cities but the number is not in the list of the chosen city.

Request :

curl -X POST -d "{\"streetNumber\":\"500\",\"streetName\":\"rue vaugirard\",\"postCode\":\"75015\",\"locality\":\"paris\"}" http://b-api-env-ap1.adb.dev.euw1.nbyt.fr/v1/customer-management/postal-addresses/normalization -H "Content-Type: application/json" -H "Authorization: Bearer at-ef003b10-01ec-402c-8719-d5313557df1a" -H "X-Source: PARTNER_NAME"

Response :

HTTP/1.1 400 Bad Request
Content-Type: application/json; charset=UTF-8
{
    "error":  "OUT_OF_BOUNDS_STREET_NUMBER",
    "error_description":  "L’adresse ne peut pas être validée car Uniserv propose une liste de secteurs de numéros"
}

Case : Error 500

Request :

curl -X POST -d "{\"streetNumber\":\"A\",\"streetName\":\"\",\"additionalInformation\":\"A\",\"postOfficeBox\":\"A\",\"postCode\":\"A\",\"locality\":\"1\"}" http://b-api-env-ap1.adb.dev.euw1.nbyt.fr/v1/customer-management/postal-addresses/normalization -H "Content-Type: application/json" -H "Authorization: Bearer at-ef003b10-01ec-402c-8719-d5313557df1a" -H "X-Source: PARTNER_NAME"

Response :

HTTP/1.1 500

Back to top

Document history

---

Version	Modification Date	Updates	API concerned	API version
0.1	22/07/2021	Initialization of the document	normalizePostalAddress	v1
0.2	23/07/2021	Translate	normalizePostalAddress	v1
0.2.1	29/07/2021	Annotations & Suggestions	normalizePostalAddress	v1

Back to top