Geocoding

Basic principles

The query includes an input address, the service returns one or several possible responses (if there is any ambiguity), including the recognised address, the position, the geocoding score, and the geocoding type.

Geocode example

{
        "url":"https://api.geoconcept.com/EU/GCW/geoconcept-web/api/lbs/geocode/v4.json",
        "type":"GET",
        "params": {
                "addressLine": {
                        "sample":"25 rue de dolbiac"},
                "postCode": {
                        "sample":"75013"},
                "city": {
                        "sample":"Paris"},
                "countryCode": {
                        "sample":"FR"},
                "maxResponses" : {
                        "type":"number","min":1,"max":20,
                        "sample":5},
                "srs":{"sample":"wgs84"}
        }
}

Parameters / Properties

Input

parameter description optional default

id

convenience identifier for this address.
Optional : this identifier has no functional role, it might be used by the caller to identify individual input addresses to geocode and output in results

yes

comment

convenience comment for this address

yes

addressLine

address including number, repetition index, type of street and street name.

yes *

addressLineExt

second address (with a street number and street name) to find if first is too bad

yes

city

city

yes *

district

district (part of city)

yes

postCode

post code

yes *

region

state, county, …

yes

countryCode

country on two or three letters (ISO code 3166-1) for example, "fr" or "fra"

yes

excludePlaces

Should responses show places, or only addresses?

yes

false

improve

try to get better results on the wrong candidates. The resulting output format may be slightly different from the candidates improved.

yes

false

maxResponses

maximum number of address results in the response

yes

5

srs

projection (EPSG code such as epsg:4326 or wgs84)

yes

Without any projection, the result will be wgs84

streetMinScore

the value of this parameters varies, as for the score, between 0 and 100.
The streetMinScore has the effect of filtering possible candidates in the following way:
If the candidate score is equal to or higher than the score, the candidate is selected as it is,
If the candidate score is lower than the score and no candidate match has already been selected, the geocoding is suggested at city level
90 is the recommended value to avoid wrong positives candidates, 50 can be used in case of manual control of the candidates

yes

0

(*) At least one of the three parameters postCode, addressLine or city must be assigned a value.

Output

parameter type min/max description

geocodedAddress (or geocodedAddresses in JSON / JSON-P)

geocodedAddress (or array in JSON / JSON-P)

0/unlimited

Geocoded addresses

id

string

0/1

identifier used in input

comment

string

0/1

comment used in input

Geocoded addresses (geocodedAddress)

parameter type min/max description

score

double

1/1

geocoding score from 0 to 100, with 100 for a perfect correspondance

geocodeType

int

1/1

type of geocoding:
- not geocoded = 0
- town = 1
- street = 2
- street enhanced = 3
- street number = 4

geocodeTypeQuality

string

1/1

geocode quality:
- "NOT_FOUND"
- "ADDRESS_POINT"
- "POI"
- "NAMED PLACE"
- "CITY+POSTCODE"
- "CITY"
- "DISTRICT+POSTCODE"
- "DISTRICT"
- "STREET"
- "ZONE+POSTCODE"
- "STREET NUMBER INTERPOLATION"
- "STREET NUMBER BOUND"
- "STREET NUMBER ESTIMATION"
- "STREET NUMBER NEAREST"
- "PONCTUAL POSTCODE"

x

double

1/1

X coordinates

y

double

1/1

Y coordinates

streetNumber

string

0/1

street number

streetWayType

string

0/1

type of street (avenue, street, etc)

streetWayName

string

0/1

street name

streetWay

string

0/1

full name of the street

addressLine

string

0/1

street found and, if there is one, the number

city

string

0/1

town found

region

string

0/1

State, County, … found, varies as a function of country, can also be empty

postCode

string

0/1

post code found

countryCode

string

1/1

Country on three letters (ISO code 3166-1)

places

Array of GeocodedAddressPlaceItem

0/unlimited

list of containing places. Output attribute values of the found address, according "placeTypes" (for example ["751010206","930005Y001XCHE"]). Depends on the country and the repository used.

Places (GeocodedAddressPlaceItem)

parameter type min/max description

placeType

string

0/1

list of types of attributes (for example ["IRIS","INSEE","…"]). Depends on the country and the repository used.

placeValue

string

0/1

list of attributes. Value of attributes for the address found, in relation to placeTypes . Depends on the country and the repository used.

Possible returns

Case of an address found (status is OK) 

{
    "status": "OK",
    "geocodedAddresses": [
        {
            "addressLine": "25 RUE DE TOLBIAC",
            "district": "13E ARRONDISSEMENT",
            "city": "PARIS",
            "countryCode": "FRA",
            "postCode": "75013",
            "score": 99.2,
            "geocodeType": 4,
            "geocodeTypeQuality": "ADDRESS_POINT",
            "x": 2.373478,
            "y": 48.828707,
            "streetNumber": "25",
            "streetWayType": "RUE",
            "streetWayName": "DE TOLBIAC",
            "streetWay": "RUE DE TOLBIAC",
            "places": [
                {
                    "placeType": "INSEE",
                    "placeValue": "75113"
                },
                {
                    "placeType": "IRIS",
                    "placeValue": "751135014"
                },
                {
                    "placeType": "LEVEL_1",
                    "placeValue": "France"
                },
                {
                    "placeType": "LEVEL_2",
                    "placeValue": "Île-de-France"
                },
                {
                    "placeType": "LEVEL_3",
                    "placeValue": "Paris"
                },
                {
                    "placeType": "LEVEL_4",
                    "placeValue": "Paris"
                },
                {
                    "placeType": "LEVEL_5",
                    "placeValue": "13e Arrondissement"
                }
            ]
        },
        {
            "addressLine": "VILLA TOLBIAC",
            "district": "13E ARRONDISSEMENT",
            "city": "PARIS",
            "countryCode": "FRA",
            "postCode": "75013",
            "score": 93.96,
            "geocodeType": 2,
            "geocodeTypeQuality": "STREET",
            "x": 2.369572,
            "y": 48.826988,
            "streetNumber": "",
            "streetWayType": "VILLA",
            "streetWayName": "TOLBIAC",
            "streetWay": "VILLA TOLBIAC",
            "places": [
                {
                    "placeType": "INSEE",
                    "placeValue": "75113"
                },
                {
                    "placeType": "IRIS",
                    "placeValue": "751135011"
                },
                {
                    "placeType": "LEVEL_1",
                    "placeValue": "France"
                },
                {
                    "placeType": "LEVEL_2",
                    "placeValue": "Île-de-France"
                },
                {
                    "placeType": "LEVEL_3",
                    "placeValue": "Paris"
                },
                {
                    "placeType": "LEVEL_4",
                    "placeValue": "Paris"
                },
                {
                    "placeType": "LEVEL_5",
                    "placeValue": "13e Arrondissement"
                }
            ]
        },
        {
            "addressLine": "PONT DE TOLBIAC",
            "district": "13E ARRONDISSEMENT",
            "city": "PARIS",
            "countryCode": "FRA",
            "postCode": "75013",
            "score": 86.91,
            "geocodeType": 2,
            "geocodeTypeQuality": "STREET",
            "x": 2.380356,
            "y": 48.832558,
            "streetNumber": "",
            "streetWayType": "PONT",
            "streetWayName": "DE TOLBIAC",
            "streetWay": "PONT DE TOLBIAC",
            "places": [
                {
                    "placeType": "INSEE",
                    "placeValue": "75113"
                },
                {
                    "placeType": "IRIS",
                    "placeValue": "751135099"
                },
                {
                    "placeType": "LEVEL_1",
                    "placeValue": "France"
                },
                {
                    "placeType": "LEVEL_2",
                    "placeValue": "Île-de-France"
                },
                {
                    "placeType": "LEVEL_3",
                    "placeValue": "Paris"
                },
                {
                    "placeType": "LEVEL_4",
                    "placeValue": "Paris"
                },
                {
                    "placeType": "LEVEL_5",
                    "placeValue": "13e Arrondissement"
                }
            ]
        },
        {
            "addressLine": "PONT DE TOLBIAC",
            "district": "12E ARRONDISSEMENT",
            "city": "PARIS",
            "countryCode": "FRA",
            "postCode": "75012",
            "score": 86.82,
            "geocodeType": 2,
            "geocodeTypeQuality": "STREET",
            "x": 2.381517,
            "y": 48.833207,
            "streetNumber": "",
            "streetWayType": "PONT",
            "streetWayName": "DE TOLBIAC",
            "streetWay": "PONT DE TOLBIAC",
            "places": [
                {
                    "placeType": "INSEE",
                    "placeValue": "75112"
                },
                {
                    "placeType": "IRIS",
                    "placeValue": "751124799"
                },
                {
                    "placeType": "LEVEL_1",
                    "placeValue": "France"
                },
                {
                    "placeType": "LEVEL_2",
                    "placeValue": "Île-de-France"
                },
                {
                    "placeType": "LEVEL_3",
                    "placeValue": "Paris"
                },
                {
                    "placeType": "LEVEL_4",
                    "placeValue": "Paris"
                },
                {
                    "placeType": "LEVEL_5",
                    "placeValue": "12e Arrondissement"
                }
            ]
        },
        {
            "addressLine": "25 RUE NEUVE TOLBIAC",
            "district": "13E ARRONDISSEMENT",
            "city": "PARIS",
            "countryCode": "FRA",
            "postCode": "75013",
            "score": 85.03,
            "geocodeType": 4,
            "geocodeTypeQuality": "ADDRESS_POINT",
            "x": 2.377029,
            "y": 48.830678,
            "streetNumber": "25",
            "streetWayType": "RUE",
            "streetWayName": "NEUVE TOLBIAC",
            "streetWay": "RUE NEUVE TOLBIAC",
            "places": [
                {
                    "placeType": "INSEE",
                    "placeValue": "75113"
                },
                {
                    "placeType": "IRIS",
                    "placeValue": "751135017"
                },
                {
                    "placeType": "LEVEL_1",
                    "placeValue": "France"
                },
                {
                    "placeType": "LEVEL_2",
                    "placeValue": "Île-de-France"
                },
                {
                    "placeType": "LEVEL_3",
                    "placeValue": "Paris"
                },
                {
                    "placeType": "LEVEL_4",
                    "placeValue": "Paris"
                },
                {
                    "placeType": "LEVEL_5",
                    "placeValue": "13e Arrondissement"
                }
            ]
        }
    ]
}

Case of an address that is not found (status is OK and no geocodedAddress) 

{
    "status": "OK",
    "geocodedAddresses": [
    ]
}

Case of a query with a non-existant reprojection system (status is ERROR) 

{
    "message":"ServiceException: Geocode failed\nGeocode failed\nFailed to process geocoding task\nUnsupported coordinate system 'epsg:5987'",
    "status":"ERROR"
}

FAQ

1. How is the score obtained in the score to be interpreted?
2. How many characters are returned in the tag postCode ?
3. What rules exist with regard to X-Y coordinates (format, coordinates range)?
4. Is this service always capable of finding a close-matching address?
5. How are Cedex entities handled?
6. Can you have all the components of an address as a single input item, in just one field?

1.

How is the score obtained in the score to be interpreted?

A strict correspondance (equivalent to a score of 100) is equivalent to a no tolerance solution in effect, for a file that must not contain any errors at all. Choosing this score, you only accept suggestions of perfect matches between the reference table and the address sought. The higher the tolerance (in other words, the lower this score is set) the more the user accepts letters that are close matches between the addresses in the file to geocode and the reference table. The more likely it will be, also, that the service will assign false coordinates to certain addresses in the file due to a faulty interpretation. It is recommended that you only keep any candidates scoring 90 or higher. This score is a good compromise to the extent that one or two approximations between the addresses to geocode and the reference table are tolerated. It is strongly recommended that candidates with a score of less that 75 are NOT retained: this corresponds to at least 4 spelling or syntax mistakes in the address. Different criteria will have a bearing on the calculation of this score:

  • the number of equivalent letters in the two strings;
  • the number of words;
  • the length of each word making up the string.

In the case of correspondances between addresses, only the names of streets have a bearing on the search for a sppelling match. The type of street has an additional incidence on the score, but only in the case where the type of street sought and the one suggested are identical.

2.

How many characters are returned in the tag postCode ?

Depends on the characteristics of postal codes for each country. Moreover, the returned string will be truncated to the first N characters if the address is not precise enough.

3.

What rules exist with regard to X-Y coordinates (format, coordinates range)?

These are names in a decimal format, with . as a separator of the decimal part. In the case where the geographic coordinates are in degrees, the return must be included within the range -180 and 180 (X=longitude) and -90 and 90 (Y=latitude), with 6 figures after the comma. In the case of projected coordinates, the result is in meters, with two figures after the comma.

4.

Is this service always capable of finding a close-matching address?

If the town does not exist, it will return an empty list.

5.

How are Cedex entities handled?

A filter is applied to not take Cedex and the codes that follow it into account during the search for addresses.

6.

Can you have all the components of an address as a single input item, in just one field?

Yes, the addressline component can be used to perform a fulltext geocoding via a unique field containing the concatenation of all fields: street number, type of street, street name, post code and name of the town. The addresses input via the addressLine component are analysed in two phases:

  • The mechanism for searching on word pattern will find, in the first instance, the town or towns present in the string. A search on the pattern then very quickly finds a label corresponding to a dictionary, in this case a dictionary of towns. This label can be badly spelt, with predictable or repeated errors in the user’s entering text at the keyboard when using Internet: duplicated latters, letters omitted, replacement of one letter with another given a similar sound to the resulting word (C instead of K, for example) part of a town name where the town name consists of several sub-entities. Following these lines of enquiry, a series of candidate towns is found in the shortest of timescales.
  • Next, the pairs of towns found + the initial string without the "town" part that has just been recognised are given to the geocoder to perform the usual geocoding operation.

Note: when the name of a town is also present in the name of a street, for example, "12 Rue d’Aix Antibes" there are potentially two candidates: Rue d’Aix à Antibes, and Rue d’Antibes à Aix. The best candidate is determined by its relative position in the string.