BeMapAPI
BeMap 4.1.0
API reference: POST /geocoding/autocomplete/1.0

REST API, Service version 1.0.0

Auto-complete#

From a textual address perform a geographical research to suggest some textual postal address (free text).

For more details: Wikipedia

Summary#

  1. Request
    1. Mandatory parameters
    2. Optional parameters
  2. Response
    1. Details of fields
    2. Response samples
    3. Error response

Request#

The request must be sent with the HTTP method POST and the HTTP header Content-Type set to application/json.

Sample: URI: /bgis/service/geocoding/autocomplete/1.0

POST data:

javascript
{
  "geoserver": "nominatim",
  "coordinate": {
    "lat": 48.8566,
    "lon": 2.3522
  },
  "place": "Paris"
}

All coordinates are defined by longitude and latitude, see the coordinate system glossary for more details.

Parameters#

NOTE: the geoserver parameter must be defined to nominatim, addok, herehlp. Otherwise the default geoserver value will be used.

  • placestringrequired

    Textual postal address or POI name. Mandatory.

  • coordinateCoordinaterequired

    To define the center of research area. Most providers use the parameter as optional, but some others require it to work. You can try a request without it, if the server returns an error message about this required parameter, add it and retry the same request.

    Coordinate fields
    • lonnumber (double)required

      Longitude in degrees decimal (WGS84).

      Also accepted as longitude.

    • latnumber (double)required

      Latitude in degrees decimal (WGS84).

      Also accepted as latitude.

  • geoserverstring

    Geoserver name.

  • swidxinteger (int32)deprecated

    Switch index.

  • languagestring

    Define the language that will be used to perform the address lookup. Objects for which defined language code is not available, default language will be used. Values language Code - An US-ASCII string that defines an ISO 639-1 (2-letter) language code. The specials 'IC' (no sensitive case) language code allows you to search for a country depending on its ISO-3166 Alpha-3 or Alpha-2 country code.

  • boundingboxBoundingBox

    Define a bounding box to limit the auto-complete search area.

    BoundingBox fields
    • minLonnumber (double)

      Minimum longitude, in degrees decimal (WGS84).

    • minLatnumber (double)

      Minimum latitude, in degrees decimal (WGS84).

    • maxLonnumber (double)

      Maximum longitude, in degrees decimal (WGS84).

    • maxLatnumber (double)

      Maximum latitude, in degrees decimal (WGS84).

  • radiusinteger (int64)

    Define the radius of research in meters.

  • countryCodestring

    Optional filtering research on country code.

  • addressDetailsboolean

    Set to true to receive the proposed postal addresses in separate fields (country, city, street, etc). false by default.

  • enLocIdboolean

    Used by HERE HLP geo-server; if set to true the Location ID will be returned.

  • enEntrancesboolean

    Enable the generation list of geo-coordinate of the access to the result (for instance the entrance).

  • enHighlightsboolean

    Enable the generation of text slices matching the query. These slices can be used to highlight the related matching fields.

  • enCategoriesboolean

    Enable the generation list of category ids. The primary category has its flag primary set to true.

  • enFoodTypesboolean

    Enable the generation list of food-type ids if available The primary category has its flag primary set to true.

  • enChainsboolean

    Enable place chains metadata to allow customers to choose a chain icon.

  • enReferencesboolean

    Enable the data source ids, when the place result has a contribution from specific suppliers.

Response#

Details of fields#

  • itemsAutocompleteElem[]

    List of proposal items.

    AutocompleteElem fields
    • elemTypestringrequired

      Type of element result. Auto-complete is able to return items of several types: categoryQuery, chainQuery, place, locality, etc.

    • placestringrequired

      Proposed place.

    • coordinateCoordinateFullNamerequired

      Coordinate of proposed place.

      CoordinateFullName fields
      • longitudenumber (double)required

        Longitude in degrees decimal (WGS84) (double).

      • latitudenumber (double)required

        Latitude in degrees decimal (WGS84) (double).

      • altitudenumber (double)

        Altitude in meters.

    • addressLabelstring

      The full address in one text string of the entity result item.

    • addressAddress

      Complete postal address of proposed place.

      Address fields
      • countryCodestring

        ISO code of country.

      • countrystring

        Country name.

      • statestring

        State name.

      • countystring

        County name.

      • citystring

        City name.

      • districtstring

        District name of city.

      • postalCodestring

        Postal code.

      • roadNumberstring

        Road number.

      • streetstring

        Street name.

      • streetNumberstring

        House number.

      • oppositeStreetNumberstringdeprecated

        Opposite street number.

    • countryCodestring

      Country Code.

    • entrancesCoordinate[]

      List of coordinate of the access to the result (for instance the entrance).

      Coordinate fields
      • lonnumber (double)required

        Longitude in degrees decimal (WGS84).

        Also accepted as longitude.

      • latnumber (double)required

        Latitude in degrees decimal (WGS84).

        Also accepted as latitude.

    • distanceinteger (int32)

      The distance in a straight line in meters from the position specified in the query coordinate parameter.

    • locationIdstring

      Location Id.

    • languagestring

      Language.

    • scorenumber (double)

      Score.

    • placeHighlightAutocompleteElemHighlight[]

      The text slices matching the query. These slices can be used to highlight the related matching place field.

      AutocompleteElemHighlight fields
      • startinteger (int32)
      • endinteger (int32)
    • addressLabelHighlightAutocompleteElemHighlight[]

      The text slices matching the query. These slices can be used to highlight the related matching address label field.

      AutocompleteElemHighlight fields
      • startinteger (int32)
      • endinteger (int32)
    • categoriesAutocompleteElemReference[]

      A list of category ids. The primary category has its flag primary set to true.

      AutocompleteElemReference fields
      • supplierIdstring
      • idstring
      • namestring
      • primaryboolean
    • foodTypesAutocompleteElemReference[]

      A list of food-type ids if available The primary category has its flag primary set to true.

      AutocompleteElemReference fields
      • supplierIdstring
      • idstring
      • namestring
      • primaryboolean
    • chainsAutocompleteElemReference[]

      Place chains metadata to allow customers to choose a chain icon.

      AutocompleteElemReference fields
      • supplierIdstring
      • idstring
      • namestring
      • primaryboolean
    • referencesAutocompleteElemReference[]

      Data source ids, when the place result has a contribution from specific suppliers:

      AutocompleteElemReference fields
      • supplierIdstring
      • idstring
      • namestring
      • primaryboolean

Response samples#

JSON Sample:

javascript
{
	"items": [{
			"place": "PARIS | ILE-DE-FRANCE | FRANCE",
			"score": 0.7,
			"coordinate": {
				"longitude": 2.38305,
				"latitude": 48.902475
			}
		}
	]
}

Error response#

If an error occurs during the process on server side, only an error object will be returned in the response. See Error example chapter.

  • code: error code.
  • message: error message.
  • coordinate: coordinate of error (optional).
    • lon: longitude of coordinate in decimal degrees (WGS84).
    • lat: latitude of coordinate in decimal degrees (WGS84).

Error example#

javascript
{ 
   "error": { 
      "code": "ERROR_CODE", 
      "message": "Comment of error.", 
      "coordinate": { 
         "lon": 8.193691832353528, 
         "lat": 45.42630127240513 
      } 
   } 
}

All coordinates are defined by longitude and latitude, see the coordinate system glossary for more details.