Autosuggest

Basic principles

This automatic completion service, or autocomplete, saves internauts time when entering place names or addresses. The function suggests likely locations as the letters of an address are typed in, or even as they are deleted, in the localisation input field.

Unlike autocompletion service, it can return places (points of interest, restaurants, monuments, etc.) in addition to addresses.

example: the internaut enters "louvre", and the service returns either:

  • Louvre museum "Musée du Louvre (Pyramide du Louvre)",
  • Underground stations "Palais Royal Musée du Louvre" and "Louvre Rivoli",
  • Town "Louvres, Île-de-France, France",
  • Car park "Le Louvre".

Autosuggest example 

{
        "url":"https://api.geoconcept.com/EU/GCW/geoconcept-web/api/lbs/autosuggest.json",
        "type":"GET",
        "params": {
                "query": {
                        "sample":"Louvre"
                },
                "maxItems": {
                        "sample":"5"
                },
                "location": {
                        "sample":"2.30432,48.79859"
                },
                "language": {
                        "sample":"fr"
                }
        }
}

Parameters / properties

Input

parameter description optional default

query

A free-text query

no

location

The center of the search area.
A coordinates couple as always easting,northing (X,Y or longitude,latitude, depending on the coordinate system given in srs parameter). Since the default coordinate system is longitude,latitude WGS84 (EPSG:4326), the default for location is longitude,latitude WGS84.

yes *

bounds

Search within a geographic area provided as a rectangle.
A bounding box, provided as always easting-min,northing-min,easting-max,northing-max (easting-min,northing-min;easting-max,northing-max is tolerated).
The coordinates depend on the coordinate system given in srs parameter.
So, with the default coordinate system the format is longitude-min,latitude-min,longitude-max,latitude-max.
Example : -284651.51,5922035.22;-99368.12,6080412.70, with srs=EPSG:3857.
This is a hard filter. Items will be returned if they are located within the specified area.

yes *

circle

Search within a geographic circular area, provided as center and radius.
So always easting,northing;radius (easting,northing;r=radius is tolerated).
Radius is always in meters. The coordinates depend on the coordinate system given in srs parameter.
So, with the default coordinate system the format is longitude,latitude;radius.
Example: -260370.793,5984549.94;10000.
This is a hard filter. Items will be returned if they are located within the specified area.

yes *

countryCode

A country (or multiple countries provided as comma-separated) alpha2 or alpha-3 country codes.

yes

srs

Coordinate system used for all coordinates (given in location parameter as input, or in AutosuggestResults’s item location as output).
The format is an EPSG coordinate system identifier.
Defaults to longitude,latitude' WGS84 (EPSG:4326).
Example : EPSG:3857 for pseudo-Mercator.

yes

language

The language to be used for result rendering as a BCP 47 compliant language code.

yes

maxItems

Maximum number of items to be retrieved.

no

5

extended

When set to true, may return resultType items that are not strictly considered as an address (such as administrativeArea, or other).

no

false

(*) At least one of the three parameters location, bounds or circle must be assigned a value.

Output

property type min/max description

items

array of AutosuggestItem

0/unlimited

List of proposed items resulting of the search.

Items (AutosuggestItem)

property type min/max description

name

string

0/1

Name of the item. Depending on the item’s resultType, it contains :
place : the place name.
locality, street, houseNumber : an address label (same as addressLabel)

resultType

string

0/1

Item’s result type. Possible values :
- place
- locality
- street
- houseNumber
- addressBlock
- intersection
- postalCodePoint
Only if extended = true:
- administrativeArea
- other

localityType

string

0/1

When resultType is locality, contains the locality type. Possible values :
- city
- district
- subdistrict
- postalCode
Empty when resultType is not locality.

categories

array of string

0/unlimited

When resultType is place, contains a the types of the place.
The first element is always the main type.
Empty when resultType is not place.

addressLabel

string

0/1

Contains an address label, that is a single string representing the item’s address.
The form of the address and the elements that compose it depend on the resultType.

location

string

0/1

Item coordinates. A coordinates couple as always easting,northing (X,Y or longitude,latitude depending on the coordinate system given in the srs request parameter). Example : -2.33844,47.26113

distance

number

0/1

required The distance of the item from the geographical search area given in the request. Always in meters.

Possible returns

The case of addresses that are found (status is OK)  

{
    "status": "OK",
    "items": [
        {
            "name": "Musée du Louvre (Pyramide du Louvre)",
            "resultType": "place",
            "addressLabel": "Musée du Louvre, 99 Musée du Louvre, 75001 Paris, France",
            "location": "2.33754,48.86053",
            "distance": 7304.0,
            "categories": [
                "Musée d'histoire",
                "Lieu d'intérêt/Attraction",
                "Attraction touristique",
                "Musée",
                "Musée d'art"
            ]
        },
        {
            "name": "Métro-Palais Royal Musée du Louvre",
            "resultType": "place",
            "addressLabel": "Place du Palais-Royal, 75001 Paris, France",
            "location": "2.33652,48.86285",
            "distance": 7524.0,
            "categories": [
                "Métro"
            ]
        },
        {
            "name": "Louvres, Île-de-France, France",
            "resultType": "locality",
            "localityType": "city",
            "addressLabel": "Louvres, Île-de-France, France",
            "location": "2.50607,49.04632",
            "distance": 31242.0
        },
        {
            "name": "Métro-Louvre Rivoli",
            "resultType": "place",
            "addressLabel": "Rue de l'Amiral de Coligny, 75001 Paris, France",
            "location": "2.34094,48.86067",
            "distance": 7405.0,
            "categories": [
                "Métro"
            ]
        },
        {
            "name": "Le Louvre",
            "resultType": "place",
            "addressLabel": "1 Rue de Marengo, 75001 Paris, France",
            "location": "2.33913,48.86185",
            "distance": 7481.0,
            "categories": [
                "Parking à étage",
                "Parking"
            ]
        }
    ]
}

The case of parameter query is empty (status is ERROR)  

{
    "message": "ServiceException: Autosuggest failed|Mandatory parameter 'query' must be defined and non-empty",
    "status": "ERROR"
}

The case of missing one of the parameters location, bounds or circle (status is ERROR)  

{
    "message": "ServiceException: Autosuggest failed|Required parameter missing. One of mutually exclusive parameters 'location', 'bounds' or 'circle' must be present",
    "status": "ERROR"
}

Prev  Up  Next
  Home