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.

Prev	Up	Next
	Home

Geoptimization API - Geoptimization REST API

Geocoding

Basic principles

Geocode example

Parameters / Properties

Possible returns

FAQ