Skip to content

Request Data Types

BrandFilter

Name Type Description Required Example
brands [ String ] List of brand IDs. Yes ["99320191"]

CategoryFilter

Name Type Description Required Example
categories [ String ] List of category IDs. Yes ["241","771"]

DetailOptions

Name Type Description Required Example
detail_level String Supported:
  • BASIC
  • FULL
 No BASIC
show_address_lines boolean An optional parameter to return formatted address in one or multiple lines. If this parameter is set, "address_lines" will be returned in response. No true

DiscoverFilters

Name Type Description Required Example
geo_filter GeoFilter Used for geo-spatial search with different types of geometries, only support RadiusGeoFilter now No {"type":"radius","radius_in_meter":2000}

DiscoverPlaceFilters

Name Type Description Required Example
ev_filter EvFilter Used for EV charge stations related filtering by EV attributes. No {"connector_types":["30001","30007"],"power_feed_levels":[2],"charger_brands":["99100001"],"free_charge":true}
geo_filter GeoFilter Used for geo-spatial discover with different types of geometries. No {"type":"BBOX","bbox":{"bottom_left":{"latitude":37.70908,"longitude":-122.50249},"top_right":{"latitude":37.7897,"longitude":-122.39108}}}

DiscoverPlaceOptions

Name Type Description Required Example
lite_result boolean If true, only basic poi attributes will be returned No true
sort_type String Desired sort of the results, default value is BEST_MATCH
Supported:
  • BEST_MATCH
  • DISTANCE
 No BEST_MATCH

EntityDiscoverBrandRequest

Name Type Description Required Example
location GeoPoint A geopoint value of the user’s location using geographic coordinates of latitude and longitude. Yes {"latitude":37.78509,"longitude":-122.41988}
category String Discovery category id. No 241
filters DiscoverFilters Support different type of filters used for discover category or brand. No {"geo_filter":{"type":"radius","radius_in_meter":2000}}
limit Integer Number of results in response. Default value: 10 No 5
locale String The preferred language for the response content. No en-US
user_id String The id associated with the user who is sending the request. No d770c779-8bdb-4f0d-82d6-480d888fad49

EntityDiscoverCategoryRequest

Name Type Description Required Example
location GeoPoint A geopoint value of the user’s location using geographic coordinates of latitude and longitude. Yes {"latitude":37.78509,"longitude":-122.41988}
category String Discovery category id. No 2040
filters DiscoverFilters Support different type of filters used for discover category or brand. No {"geo_filter":{"type":"radius","radius_in_meter":2000}}
limit Integer Number of results in response. Default value: 10 No 5
locale String The preferred language for the response content. No en-US
user_id String The id associated with the user who is sending the request. No d770c779-8bdb-4f0d-82d6-480d888fad49

EntityDiscoverPlaceRequest

Name Type Description Required Example
categories [ String ] List of category IDs. Yes ["771"]
location GeoPoint Geo-coordinate of the user location. Yes {"latitude":37.78509,
"longitude":-122.41988}
discover_options DiscoverPlaceOptions Discover options to customize discover behavior. No {"lite_result":true}
filters DiscoverPlaceFilters Discover filters No {"geo_filter":{"type":"radius",
"radius_in_meter":5000}}
limit Integer Number of results in response. Default value: 10 No 5
locale String The preferred language for the response content. No en-US
user_id String The id associated with the user who is sending the request. No d770c779-8bdb-4f0d-82d6-480d888fad49

EntityEvChargingOnRouteRequest

Name Type Description Required Example
route String Route points of the corridor. Support two types of format:
1. Geo-coordinate list (separated by ";" ); for example, "route=37.1245,-122.45678;37.1246,-122.45679;37.1247,-122.45690;37.1248,-122.45691;".
2. Encoded polyline format. Refer Polyline Algorithm. Example: "route=a{qaFziljVU@"		 Yes a{qaFziljVU@,
location GeoPoint Geo-coordinate of the user location. Yes {"latitude":37.78509,"longitude":-122.41988}
ev_context EvContext Vehicle current energy info, including current energy, current range, low energy threshold Yes {"state_of_charge":75,"low_energy_threshold":30,"remaining_range_in_km":40}
ev_filter EvFilter Used for EV charge stations related filtering by EV attributes. No {"connector_types":["30001","30007"],"power_feed_levels":[2],"charger_brands":["99100001"],"free_charge":true}
locale String The preferred language for the response content. No en-US
user_id String The id associated with the user who is sending the request. No d770c779-8bdb-4f0d-82d6-480d888fad49

EntityEvNearbySearchRequest

Name Type Description Required Example
location GeoPoint Geo-coordinate of the user location. Yes {"latitude":37.78509,"longitude":-122.41988}
ev_filter EvFilter Used for EV charge stations related filtering by EV attributes. No {"connector_types":["30001","30007"],"power_feed_levels":[2],"charger_brands":["99100001"],"free_charge":true}
limit Integer Number of results in response. Default value: 10 No 5
locale String The preferred language for the response content. No en-US
user_id String The id associated with the user who is sending the request. No d770c779-8bdb-4f0d-82d6-480d888fad49

EntityGetCategoriesRequest

Name Type Description Required Example
locale String The preferred language for the response content. No en-US
user_id String The id associated with the user who is sending the request. No d770c779-8bdb-4f0d-82d6-480d888fad49

EntityGetDetailRequest

Name Type Description Required Example
entity_ids [ String ] List of place or address id for details lookup. Yes ["P-1012321","P-1012322"]
detail_options DetailOptions Options to customize detail request behavior. No {"detail_level":"FULL",
"show_address_lines":true}
facet_parameters FacetParameters Parameters to specify facet related search result. No {"parking_parameters":
{"entry_time":"2020-10-28T22:00"}}
location GeoPoint A geopoint value of the user’s location using geographic coordinates of latitude and longitude. No {"latitude":37.78509,
"longitude":-122.41988}
locale String The preferred language for the response content. No en-US
user_id String The id associated with the user who is sending the request. No d770c779-8bdb-4f0d-82d6-480d888fad49

EntityPredictionSuggestionRequest

Name Type Description Required Example
location GeoPoint A geopoint value of the user’s location using geographic coordinates of latitude and longitude. Yes {"latitude":37.78509,
"longitude":-122.41988}
limit Integer Number of results in response. Default value: 10 No 5
locale String The preferred language for the response content. No en-US
query String The suggestion text in the form of a partial query. No Star
suggestion_options SuggestionOptions Suggestion options to customize suggestion behavior. No {"include_entity":true}
user_id String The id associated with the user who is sending the request. No d770c779-8bdb-4f0d-82d6-480d888fad49

EntityPredictionWordRequest

Name Type Description Required Example
location GeoPoint A geopoint value of the user’s location using geographic coordinates of latitude and longitude. Yes {"latitude":37.78509,
"longitude":-122.41988}
query String The partial word text. Yes Star
limit Integer Number of results in response. Default value: 10 No 5
locale String The preferred language for the response content. No en-US
user_id String The id associated with the user who is sending the request. No d770c779-8bdb-4f0d-82d6-480d888fad49

EntitySearchByExitRequest

Name Type Description Required Example
location GeoPoint A geopoint value of the user’s location using geographic coordinates of latitude and longitude. Yes {"latitude":37.78509,
"longitude":-122.41988}
categories [ String ] Category ids, which expect to be found near the exit location. Yes ["811", "241"]
exits [ ExitPoint ] Exit points, each one will be used to search for all categories and returned in response Yes {"location":{"latitude":37.58124,
"longitude":-121.32358},
"type":"REST_AREA"}
locale String The preferred language for the response content. No en-US
radius_in_meter double Search radius in meter No 2000
user_id String The id associated with the user who is sending the request. No d770c779-8bdb-4f0d-82d6-480d888fad49

EntitySearchRequest

Name Type Description Required Example
location GeoPoint Geo-coordinate of the current vehicle position location.
If parameter anchor doesn't exist,
location will be used as the search anchor.		 Yes {"latitude":37.78509,
"longitude":-122.41988}
anchor GeoPoint Geo-coordinate of the search anchor point No {"latitude":37.78509,
"longitude":-122.41988}
facet_parameters FacetParameters Parameters to specify facet related search result. No {"parking_parameters":
{"entry_time":"2020-10-28T22:00"}}
filters SearchFilters Search filters No {"geo_filter":{"type":"BBOX",
"bbox":{"bottom_left":{"latitude":37.78336,
"longitude":-122.43394},
"top_right":{"latitude":37.7951,
"longitude":-122.40742}}},
"category_filter":{"categories":["771"]}}
limit Integer Number of results in response. Default value: 10 No 5
locale String The preferred language for the response content. No en-US
page_context String Parameter to fetch the search results for next page.
If page_context is passed in the request,
all other parameters will be ignored.		 No
query String Support free text query and multibox query. No Starbucks
search_options SearchOptions Search options to customize search behavior. No {"intent":"around",
"show_address_lines":true}
user_id String The id associated with the user who is sending the request. No d770c779-8bdb-4f0d-82d6-480d888fad49

EvContext

Name Type Description Required Example
low_energy_threshold double Energy in percentage that makes the driver feel safe Yes 10
remaining_range_in_km double Current remaining range in Km Yes 150
state_of_charge double Current remaining electric energy in percentage Yes 75

EvFilter

Name Type Description Required Example
charger_brands [ String ] EV charger brands list. No ["99100001"]
connector_types [ String ] EV connector types. Supported:
  • 30001 : J1772
  • 30002 : SAE Combo
  • 30003 : CHAdeMO
  • 30004 : Type 2
  • 30005 : Type 3
  • 30006 : Tesla
  • 30007 : NEMA
  • 30008 : NEMA 14-50
  • 30009 : Plug Type F
 No ["30006", "30007"]
free_charge boolean Free or not. If true, return the free connector, otherwise return the paid. No true
power_feed_levels [ Integer ] EV power feed levels. Supported:
  • 1 : Level 1
  • 2 : Level 1
  • 5 : DC Fast
  • 6 : Ultra Fast
 No [5]
customer_charge_levels [ Integer ] EV customer charge levels. Supported:
  • 1 : Normal charge, maxPower <= 6kW
  • 2 : Sem-fast charge, 6KW < maxPower <= 15KW
  • 3 : Fast charge, 15KW < maxPower <= 50KW
  • 4 : Super fast charge, maxPower > 50KW
No [3]
filter_types [ String ] It is used to declare the type of each filter, refer to FilterTypeField No [{"field": "CHARGER_BRANDS","type": "EXCLUDE"}]
min_power double Min power in KW No 50
max_power double Max power in KW No 100
available boolean Available or not. If true, return the available connector, otherwise return all. No true

FilterTypeField

Name Type Description Required Example
field String The display name of the filter. Supported:
  • CHARGER_BRANDS
 Yes "CHARGER_BRANDS"
type String The type of filter. Supported:
  • INCLUDE
  • EXCLUDE
 Yes "EXCLUDE"

ExitPoint

Name Type Description Required Example
location GeoPoint Exit location Yes {"latitude":37.78509,"longitude":-122.41988}
type String Exit type. Supported:
  • REST_AREA
  • EXIT_POINT
 No REST_AREA

FacetFieldParameters

Name Type Description Required Example
facet_fields [ String ] Specify the type of result facet returned in the search results. Supported:
  • CHARGER_BRAND
  • POWER_FEED_LEVEL
 No ["CHARGER_BRAND", "POWER_FEED_LEVEL"]

FacetParameters

Name Type Description Required Example
facet_field_parameters FacetFieldParameters Parameters to specify the type of result facet returned in the search results. No {"facet_fields":["CHARGER_BRAND"]}
parking_parameters ParkingParameters Set the expected parking time and duration, when the data supports price estimation, the estimated cost is returned through the response.
Refer ParkingPrice.calculated_rates		 No {"entry_time":"2020-10-28T22:00","duration":120}
additional_facetAttributes [ String ] Additional facet attributes, supported:
  • LINKED_ENTITY
Refer AdditionalFacetAttributeType		 No ["LINKED_ENTITY"]

GeoFilter

Name Type Description Required Example
type String GeoFilter that can be used for geo spatial search with different types of geometries. Supported: No BBOX

GeoPoint

Name Type Description Required Example
latitude double The latitude of the location in degrees Yes 37.78509
longitude double The longitude of the location in degrees Yes -122.41988

ParkingParameters

Name Type Description Required Example
duration Integer Parking duration in minutes to calculate parking price. Works together with entry_time. Default value is 60 No 30
entry_time String Entry time to calculate parking price in format "yyyy-MM-ddTHH:mm" or "yyyy-MM-ddTHH:mmZ"
(Note: if "Z" is added, will be treated as UTC time, otherwise treated locally).		 No 2019-03-08T15:00

SearchFilters

Name Type Description Required Example
brand_filter BrandFilter Used for filtering by entity brand IDs. No {"brands":["99100003"]}
category_filter CategoryFilter Used for filtering by category IDs. No {"categories":["771"]}
ev_filter EvFilter Used for EV charge stations related filtering by EV attributes. No {"connector_types":["30003"],
"power_feed_levels":[5]}
geo_filter GeoFilter Used for geo-spatial search with different types of geometries. No {"type":"BBOX","bbox":{"bottom_left":
{"latitude":37.78034,"longitude":-122.42472},
"top_right":{"latitude":37.80042,
"longitude":-122.40138}}}
business_filter BusinessFilter Used for filtering by business-related attributes. No {"open_now":true,"rating_filter":{"min_rating":4.0}}

SearchOptions

Name Type Description Required Example
intent String Intent of the search,supported:
  • AROUND
  • NEAR_DESTINATION
  • PREDICTION
  • REVERSE_GEOCODING
Refer to Intent		 No SearchOptions
show_address_lines boolean An optional parameter to return formatted address in one or multiple lines. If this parameter is set, "address_lines" will be returned in response. No true
trigger String Trigger some special search. Supported:
  • VOICE
 No VOICE

SuggestionOptions

Name Type Description Required Example
include_entity boolean No true

BBoxGeoFilter

Name Type Description Required Example
bbox BBox For bounding box search. Two geo-coordinates (bottom-left, top-right) for bounding box search are required. Yes {"type":"BBOX","bbox":{"bottom_left":
{"latitude":37.78034,"longitude":-122.42472},
"top_right":{"latitude":37.80042,
"longitude":-122.40138}}}
type String Get geo filter type of the filter, constant value: BBOX Yes BBOX

BBox

Name Type Description Required Example
bottom_left GeoPoint The bottom left geo-coordinates of the bounding box Yes
top_right GeoPoint The top right geo-coordinates of the bounding box Yes

PolygonGeoFilter

Name Type Description Required Example
polygon Polygon A polygon described by a list of geo-coordinates (at least three) Yes {"points":[{"latitude":37.78034,"longitude":-122.42472},{"latitude":37.80042,"longitude":-122.40138}]}
type String Get geo filter type of the filter, constant value: POLYGON Yes POLYGON

Polygon

Name Type Description Required Example
points [GeoPoint] The list of geo-coordinates for a polygon Yes

CorridorGeoFilter

Name Type Description Required Example
type String Get geo filter type of the filter, constant value: CORRIDOR Yes ORRIDOR
route String Route points of the corridor. Support two types of format:
1. Geo-coordinate list (separated by ";" ); for example, "route=37.1245,-122.45678;37.1246,-122.45679;37.1247,-122.45690;37.1248,-122.45691;".
2. Encoded polyline format. Refer Polyline Algorithm. Example: "route=a{qaFziljVU@"		 Yes a{qaFziljVU@
route_width Integer The width in meters used for corridor search. Default value is 1600m and max is 2000m. No 1800

RadiusGeoFilter

Name Type Description Required Example
radius_in_meter Integer Specify search radius in meters for nearby search. Yes 1600
type String Get geo filter type of the filter, constant value: RADIUS. Yes RADIUS

BusinessFilter

Name Type Description Required Example
open_now boolean If true, the API will return the POI that is currently open. false true
newly_open boolean If true, the API will return the POI that is newly opened. false true
reservation boolean If true, the API will return the POI that is reservation-supported. false true
amenities [ String ] Filtering POI by amenities IDs. false ["2", "17"]
rating_filter RatingFilter Filtering POI by rating. false {"min_rating":3.0,"max_rating":5.0}
price_filter PriceFilter Filtering POI by price level. false {"price_levels":[2, 3]}

RatingFilter

Name Type Description Required Example
min_rating double The supported range is [1, 5] and min_rating should be always <= max_rating false 3.0
max_rating double The supported range is [1, 5] and min_rating should be always <= max_rating false 4.5

PriceFilter

Name Type Description Required Example
price_levels [ int ] Price level, support: 1, 2, 3, 4 true [1,2]

AdditionalFacetAttributeType

Value Description
LINKED_ENTITY Used to trigger the return of related entities facet when lookup for a single address.

Intent

Value Description
AROUND Finds relevant entities based on location, default value.
NEAR_DESTINATION Finds nearby relevant entities around destination location.
REVERSE_GEOCODING Finds addresses based on coordinates (lat,lon).
PREDICTION Get prediction results based on user's profile, not supported now.