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

REST API, Service version 1.0.0

Natural Geocoding service#

Natural Geocoding is the process of converting textual postal address (1 line / free text) to a geographical longitude and latitude coordinates.

For more details: Wikipedia

Summary#

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

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/1.0/natural

POST data:

javascript
{
	"geoserver": "herehlp",
	"naturalQuery": "Villa des pyrénées paris france"
}

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

Parameters#

  • naturalQuerystringrequired

    The free-textual postal address request.

  • geoserverstring

    Geoserver name.

  • swidxinteger (int32)deprecated

    Switch index.

  • boundingBoxBoundingBox

    Define a bounding box (in WGS84 format) to restrict the geocoding research.

    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).

  • assetSearchTypeenum

    Define the search type of asset.

    4 accepted values
    OBJECTOBJECT.
    POIPOI.
    CITY_CENTERCITY_CENTER.
    ROADROAD.
  • searchTypeenum

    Defines all the possible types of research that can be applied to a textual pattern.

    6 accepted values
    CONTAINSMeans that the pattern must be contained in the required strings.
    FUZZYMeans that the pattern will be used to perform a fuzzy search based on. the pattern. (Fuzzy searching can be useful when you are searching text that may contain misspelled words).
    KEY_SEARCHSpecifies a search on key ids. This criteria can be used for retrieving an item by its numerical key.
    STRICTMeans that the required string must be strictly equal to the pattern.
    STRICT_BEGINNINGMeans that the required strings must begin with the pattern.
    WORD_BEGINNINGMeans that one word of required strings must begin with the pattern (characters ' ', '-' and '/' are considered as word separators).
  • maximumResultsinteger (int32)

    The maximum number of items used to perform the research and returned items by the server.

    Also accepted as maximunResult.

  • languagestring

    Define the language that will be used to perform the address lookup.

  • locIdEnableboolean

    Used by HERE HLP geo-server to define the location ID.

Response#

Details of fields#

  • extentBoundingBox

    Define a bounding box (in WGS84 format) to restrict the geocoding research.

    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).

  • elementsGeocodingItem[]

    Define geocoding elements for a featured road.

    GeocodingItem fields
    • boundingBoxBoundingBox

      Define a bounding box (in WGS84 format) to restrict the geocoding research.

      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).

    • coordinateCoordinate

      Matched coordinate on a road.

      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.

    • exactCoordinateCoordinate

      Exact coordinate is a non map-matched coordinate on road.

      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.

    • distanceFromRequestnumber (double)

      Distance in meters between the request coordinate and the matched coordinate.

    • postalAddressAddress

      Postal address.

      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.

    • oppositePostalAddressAddress

      Opposite postal address. Optional field, can be enable with option OPPOSITE_POSTAL_ADDRESS of OPPOSITE_POSTAL_ADDRESS_ALWAYS.

      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.

    • postalAddressClassTypeenum

      Postal address.

      177 accepted values
      __NOT_MAPPEDNot mapped value.
      EARTH_SURFACEEarth surface.
      COUNTRYCountry.
      ORDRE_1_AREAState, Region, etc.
      ORDRE_2_AREAArea 2.
      ORDRE_3_AREAArea 3.
      ORDRE_4_AREAArea 4.
      ORDRE_5_AREAArea 5.
      ORDRE_6_AREAArea 6.
      ORDRE_7_AREADepartment, etc.
      ORDRE_8_AREACity.
      ORDRE_9_AREADistrict.
      POSTAL_DISTRICTPostal district.
      EXT_POSTAL_CODEExtended Digit Postal Code (ie 7-Digit PC on UK).
      ISLANDIsland.
      BUILT_UP_AREAUrban area, not an administrative area.
      BUILT_UP_AREA_2Secondary urban areas (not an administrative area).
      BUILT_UP_AREA_3Other urban areas (not an administrative area).
      LOW_EM_ZONELow Emission Zone (LEZ).
      LAND_USAGEParc/garden, industrial area, industrial harbour area.
      LAND_COVERAGEWoodland, moor/heathland, beach/dune/sand.
      WATER_ELEMENTOcean, sea, lac, river, etc. Main.
      WATER_ELEMENT_2Ocean, sea, lac, river, etc. Secondary.
      WATER_ELEMENT_3Ocean, sea, lac, river, etc. Third.
      WATER_ELEMENT_4Ocean, sea, lac, river, etc. Fourth.
      OTHER_AREASMilitary base, native american reserve, etc.
      AIRPORT_AREAAirport contour, ports.
      AIRCRAFT_ROADAircraft roads.
      BUILDINGBuilding contour.
      RAILWAY_ELEMENTRailway.
      ROAD_ELEMENT_MINMin value for road elements (Range : 4000 - 6899).
      ROAD_FOURTH_PEDESTRIANFourth - Pedestrian.
      ROAD_FOURTH_ROUNDABOUTFourth - Roundabout.
      ROAD_FOURTH_SLIPROADFourth - Slip road.
      ROAD_FOURTHSUNDAY.
      ROAD_FOURTH_MOTORWAYFourth - Motorway.
      ROAD_FOURTH_FERRYFourth - Ferry.
      ROAD_TERTIARY_PEDESTRIANTertiary - Pedestrian.
      ROAD_TERTIARY_ROUNDABOUTTertiary - Roundabout.
      ROAD_TERTIARY_SLIPROADTertiary - Slip road.
      ROAD_TERTIARYTertiary.
      ROAD_TERTIARY_MOTORWAYTertiary - Motorway.
      ROAD_TERTIARY_FERRYTertiary - Ferry.
      ROAD_SECONDARY_PEDESTRIANSecondary - Pedestrian.
      ROAD_SECONDARY_ROUNDABOUTSecondary - Roundabout.
      ROAD_SECONDARY_SLIPROADSecondary - Slip road.
      ROAD_SECONDARYSecondary.
      ROAD_SECONDARY_MOTORWAYSecondary - Motorway.
      ROAD_SECONDARY_FERRYSecondary - Ferry.
      ROAD_MAIN_PEDESTRIANMain - Pedestrian.
      ROAD_MAIN_ROUNDABOUTMain - Roundabout.
      ROAD_MAIN_SLIPROADMain - Slip road.
      ROAD_MAINMain Road.
      ROAD_MAIN_MOTORWAYMain - Motorway.
      ROAD_MAIN_FERRYMain - Ferry.
      ROAD_ELEMENT_MAXMax value for road elements (Range : 4000 - 6899).
      KB_ROUTE_CLASSClass for dynamic route forms.
      TRAFFIC_FLOWClass for dynamic traffic flow forms.
      UNDETAILED_MAIN_MOTORWAYDuplication of ROAD_MAIN_MOTORWAY for undetailed zoom level display.
      TOLL_SYSTEMToll Sys.
      TOLL_STRUCTUREToll Structures.
      TMC_LOCATIONClass of TMC locations.
      COMPLEX_RESTRICTIONComplex restriction (chained, time dependent, vehicle profile dependent) definitions for manoeuvres in road network.
      POINT_ADDRESSPoint Addresses.
      SIGN_POST_COLORSign Post colors for panels display.
      LANE_CONNECTIONLane to lane connections in road network.
      SIGN_POST_NUMBERSign post number (an exit number).
      RESTRICTIONRestriction definitions for manoeuvres in road network.
      JUNCTIONBorder nodes of road network.
      NODENodes of road network.
      CAPITALNational or regional capitals (cities).
      WORLD_CAPITALSWorld capitals (from world.svs file).
      POLICE_RADARPolice radars (Not contained in default SVS datasets).
      LANDMARKS_2D2D Landmarks.
      VEHICLE_REPAIRVehicle repair facility.
      PETROL_STATIONPetrol station.
      RENT_A_CARRent a car facility.
      PARKING_GARAGEParking garage.
      HOTEL_MOTELHotel or motel.
      RESTAURANTRestaurant.
      TOURIST_OFFICETourist office.
      MUSEUMTourist office.
      THEATRETheatre.
      CULTURAL_CENTRECultural centre.
      SPORTS_ACTIVITYSports activity.
      HOSPITALHospital polyclinic.
      POLICE_STATIONPolice station.
      CITY_HALLCity hall.
      POST_OFFICEPost office.
      PHARMACYPharmacy.
      BANKBank.
      SKI_RESORTSki resort.
      PANORAMIC_VIEWScenic / panoramic view.
      SWIMMING_POOLSwimming pool.
      WORSHIP_PLACEPlace of worship.
      FERRY_TERMINALFerry terminal.
      AIRLINE_ACCESSAirline access.
      CAMPING_GROUNDCamping ground.
      COMMUNITY_CENTRECommunity centre.
      EMBASSYEmbassy.
      FRONTIER_CROSSINGFrontier crossing.
      GOVERNMENT_OFFICEGovernment office.
      MOTORING_ORG_OFFICEMotoring organization office.
      OPEN_PARKING_AREAOpen parking area.
      RECREATION_FACILITYRecreation facility.
      SCHOOLSchool.
      SHOPPING_CENTREShopping centre.
      STADIUMStadium.
      TOURIST_ATTRACTIONTourist attraction.
      UNIVERSITYUniversity or college.
      BUSINESS_FACILITYBusiness facility.
      CITY_CENTERCity center.
      RAILWAY_STATIONRailway station.
      HAMLETHamlet.
      AIRPORTAirport.
      BUS_STATIONBus station.
      EXHIBITION_CENTERExhibition centre.
      PARK_AND_RIDEPark and ride.
      REST_AREARest area.
      KB_GOLF_COURSEGolf course.
      ATMATM.
      GROCERY_STOREGrocery store.
      LIBRARYLibrary.
      MARINAMarina.
      COMMUTER_RAIL_STATIONCommuter rail station.
      COURT_HOUSECourt house.
      HISTORICAL_MONUMENTHistorical monument.
      BOWLING_CENTREBowling centre.
      CASINOCasino.
      CINEMACinema.
      ICE_SKATING_RINKIce skating rink.
      NIGHTLIFENightlife.
      PUBLIC_SPORT_AIRPORTPublic sport airport.
      SPORTS_CENTRESports centre.
      WINERYWinery.
      AUTOMOBILE_DEALERSHPAutomobile/Motorcycle dealership.
      COMPANYCompany.
      BEACHBeach.
      SHOPShop.
      PARK_AND_RECREATION_AREAPark and recreation area.
      MOUNTAIN_PEAKMountain peak.
      OPERAOpera.
      CONCERT_HALLConcert hall.
      TENNIS_COURTTennis court.
      WATER_SPORTWater sport.
      MUSIC_CENTERMusic center.
      DOCTORDoctor.
      DENTISTDentist.
      VETERINARIANVeterinarian.
      CONVENTION_CENTERConvention center.
      LEISURE_CENTRELeisure centre.
      YACHT_BASINYacht basin.
      BAR_PUBBar/Pub.
      ENTERTAINMENTEntertainment.
      ABBEYAbbey.
      AMUSEMENT_PARKAmusement park.
      ARTS_CENTERArts center.
      BUILDING_FOOTPRINTBuilding footprint.
      CASTLECastle.
      CHURCHChurch.
      FORTRESSFortress.
      CAR_DEALERCar dealer.
      HOLIDAY_AREAHoliday area.
      LIGHTHOUSELighthouse.
      MILITARY_CEMETERYMilitary cemetery.
      MONASTERYMonastery.
      MONUMENTMonument.
      NATURAL_RESERVENatural reserve.
      PRISONPrison.
      ROCKSRocks.
      WALKING_AREAWalking area.
      WATER_MILLWater mill.
      WINDMILLWindmill.
      ZOOZoo.
      RENT_A_CAR_PARKINGRent-a-Car parking.
      MOUNTAIN_PASSMountain pass.
      HIGHLIGHT_CLASSHighlight.
    • postalAddressClassIdinteger (int64)

      Postal address.

    • postalAddressExactStreeNumberboolean

      Indicates if the location corresponds exactly to the required street number.

    • anglenumber (double)

      Angle.

    • administrativeSpeedLimitnumber (float)

      Speed limit.

    • relevanceScorenumber (double)

      Global matching error.

    • countryRelevanceScorenumber (double)

      Matching error of the country.

    • cityRelevanceScorenumber (double)

      Matching error of the city.

    • postalCodeRelevanceScorenumber (double)

      Matching error of the postal code (zip code).

    • streetRelevanceScorenumber (double)

      Matching error of the place.

    • streetNumberRelevanceScorenumber (double)

      Matching error of the house number (street number).

    • roadInfoRoadInfo

      Road information.

      RoadInfo fields
      • urbanboolean

        Urban / not urban flag.

      • tunnelboolean

        A flag that indicates if road is part of a tunnel or not.

      • bridgeboolean

        A flag that indicates if road is part of a bridge or not.

      • maxSpeedVerifiedboolean

        Maximum speed verified flag (true: verified, false: calculated).

      • carPoolboolean

        A flag that indicates if road is reserved to carpooling.

      • mainCategoryboolean

        A flag that enables discrimination within road's of a same FCC type (depends of map provider).

      • dualCarriagewayinteger (int32)

        A flag that indicates if road is part of a dual carriageway (e.g. with physical separation between opposite traffic sides).

      • noThroughTrinteger (int32)

        No through traffic restriction.

      • tollinteger (int32)

        Toll information.

      • taxinteger (int32)

        Indicates if road is submitted to a government tax (like German MAUT, etc). 0 means no tax, 1-3 defines the tax category (country dependent).

      • matchDirenum

        The matching direction.

        4 accepted values
        CLOSE0 : Undefined matched direction and closed in both directions.
        OPEN_POS1 : open in positive direction.
        OPEN_NEG2 : open in negative direction.
        OPEN3 : Undefined matched direction and open in both directions.
      • nbLanePosinteger (int32)

        Number of lanes in positive direction. 0 if traffic closed in positive direction or if lane information is not available.

      • nbLaneNeginteger (int32)

        Number of lanes in negative direction. 0 if traffic closed in negative direction or if lane information is not available.

      • pedestrianInfrastructureTypeenum

        Enum of pedestrian type.

        11 accepted values
        UNDEFINEDUndefined.
        ZONEPedestrian Zone.
        HIKINGHiking.
        UNPAVED_ROADUnpaved Road.
        ROUGH_ROADRough Road.
        CONDITION_ROADPoor Condition Road.
        STAIRSStairs.
        TUNNELTunnel.
        ELEVATORElevator.
        ESCALATOREscalator.
        FOOTBRIDGEFootbridge.
      • maxSpeednumber (float)

        Speed limit in kph (0 if not available).

      • averageSpeednumber (float)

        Average speed in kph.

      • conditionalMaxSpeedsConditionalSpdLimit[]

        Optional conditional speed limit.

        ConditionalSpdLimit fields
        • speednumber (float)required

          The speed limit in kph.

        • typeenumrequired

          Condition type.

          9 accepted values
          NONENo speed situation.
          HAZMATHazardous material.
          TRAILERTrailer.
          WEIGHTWeight.
          WEATHERWeather.
          VEHICLE_TYPEVehicle type.
          VEHICULE_TYPEVehicle type. Deprecated use VEHICLE_TYPE instead.
          SCHOOLSchool.
          ADVISORYAdvisory.
        • valuestringrequired

          Condition value (see HAZMAT, WEATHER, WEIGHT...)

      • lengthinteger (int32)

        Length in meters.

      • directionFlowenum

        The direction of traffic flow per transportation modes (use CartoConst to access to corresponding mode in dirFlow).

        4 accepted values
        CLOSE0 : closed in both directions.
        OPEN_POS1 : open in positive direction.
        OPEN_NEG2 : open in negative direction.
        OPEN3 : open in both directions.
    • geoElementTypesenum[]

      .

      61 accepted values
      ALL_ROADRoad types.
      PEDESTRIAN
      ROUNDABOUT
      SLIP_ROAD
      ROAD
      MOTORWAY
      FERRY
      MAIN_ROADRoad levels.
      SECONDARY_ROAD
      TERTIARY_ROAD
      FOURTH_ROAD
      COUNTRYAdministrative.
      STATE
      COUNTY
      CITY
      DISTRICT
      POSTAL_CODE
      BUILT_UP_AREA_NAUrban area information not available.
      BUILT_UP_AREA_NONENo urban area.
      BUILT_UP_AREA_MAINUrban area coverage size main, not an administrative area.
      BUILT_UP_AREA_MEDIUMUrban area coverage size medium (not an administrative area).
      BUILT_UP_AREA_SMALLUrban area coverage size small (not an administrative area).
      VEHICLE_REPAIRPOI.
      PETROL_STATION
      RENT_A_CAR
      PARKING_GARAGE
      HOTEL_MOTEL
      RESTAURANT
      TOURIST_OFFICE
      MUSEUM
      THEATRE
      CULTURAL_CENTRE
      SPORTS_ACTIVITY
      HOSPITAL
      POLICE_STATION
      CITY_HALL
      POST_OFFICE
      PHARMACY
      BANK
      CAMPING
      SHOPPING_CENTRE
      STADIUM
      TOURIST_ATTRACTION
      BUS_STATION
      EXHIBITION_CENTER
      GOLF_COURSE
      GROCERY_STORE
      LIBRARY
      MARINA
      HISTORICAL_MONUMENT
      BOWLING
      CASINO
      CINEMA
      SPORTS_CENTRE
      BEACH
      SHOP
      OPERA
      TENNIS_COURT
      MUSIC_CENTER
      AMUSEMENT_PARK
      ZOO
    • polylineCoordinate[]

      Polyline.

      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.

    • segmentIdinteger (int64)

      Segment id.

    • trafficElementsTrafficItem[]

      .

      TrafficItem fields
      • infoTrafficElementInfo

        Traffic information of element.

        TrafficElementInfo fields
        • idstring
        • countryCodestring
        • copyrightstring
        • releaseDatestring (date-time)
        • lastUpdateDatestring (date-time)
      • elementIdstring

        Element ID.

      • reverseDirectionboolean

        True for inverse road direction.

      • boundingBoxBoundingBox

        Bounding box of geometry in WGS84.

        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).

      • jamFactornumber (float)

        Percent (%) of traffic jam. Between 0.00 (free way) to 100.00 (full jam).

      • reasonenum

        TrafficReason.

        10 accepted values
        NANot available.
        CONGESTIONtraffic congestion (jam).
        CARRIAGEWAY_REDUCEDCarriage-way reduced.
        ACCIDENTAccident.
        INCIDENTIncident.
        INFORMATIONInformation.
        NON_RECOMMANDED_ROADNon re-commanded road.
        ROAD_CONDITION_DETERIORATEDRoad condition deteriorated.
        BLOCKED_ROADBlocked road.
        ROAD_UNDER_CONTRUCTIONRoad under construction.
      • reasonCommentsTrafficResComment[]

        List of reason comments.

        TrafficResComment fields
        • languagestring
        • commentstring
      • reasonCoordinateCoordinate

        Coordinate of the reason event.

        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.

      • polylineCoordinate[]

        Polyline.

        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.

      • segmentInfosTrafficSegInfo[]

        Segment Info.

        TrafficSegInfo fields
        • idstring

          Unique identifier of road segment.

        • reverseDirectionboolean

          The route travel is in opposite way of geometry.

      • tmcInternalIdinteger (int64)

        AlertcTrafficElement.

      • alertcEbuCountryCodestring

        AlertcTrafficElement.

      • alertcTableIdinteger (int64)

        AlertcTrafficElement.

      • alertcLocationIdinteger (int64)

        AlertcTrafficElement.

      • alertcExtendinteger (int32)

        AlertcTrafficElement.

      • alertcCodeinteger (int32)

        AlertcTrafficElement.

      • openLrBase64string

        OpenLrTrafficElement.

  • maximunResultinteger (int32)

    The maximum number of items used to perform the research and returned items by the server.

Response samples#

JSON Sample:

javascript
{
    "elements": [
        {
            "boundingBox": {
                "minLon": 2.40498,
                "minLat": 48.85325,
                "maxLon": 2.40587,
                "maxLat": 48.85351
            },
            "coordinate": {
                "lon": 2.40542,
                "lat": 48.85339
            },
            "distanceFromRequest": 0.0,
            "postalCode": {
                "countryCode": "FRA",
                "country": "France",
                "state": "Île-de-France",
                "county": "Paris",
                "city": "Paris",
                "district": "20e Arrondissement",
                "postalCode": "75020",
                "street": "Villa des Pyrénées"
            },
            "postalAddressClassId": 0,
            "postalAddressExactStreeNumber": false,
            "angle": 0.0,
            "administrativeSpeedLimit": 0.0,
            "relevanceScore": 1.0,
            "countryRelevanceScore": 0.0,
            "cityRelevanceScore": 0.0,
            "postalCodeRelevanceScore": 0.0,
            "streetRelevanceScore": 0.0,
            "streetNumberRelevanceScore": 0.0,
            "segmentId": 0
        }
    ],
    "maximumResult": 0
}