This document supports Location Based Services REST Interface Version 2. (For the API Reference for Location Based Services REST Interface Version 1, Go Here.)
Location Based Service Call Groups
Get Saved Search History (Queries)
GeoFencing and GeoMessaging Calls
This is the complete reference for Intel® Cloud Services Platform beta Location Based Services REST Interface Version 2. This discussion assumes that you already have a basic understanding of the Location BasedServices REST APIs. If not, see the Intel Cloud Platform Services Location Based Services REST Developer's Guide.
REST vs. JavaScript*
Primary use of Location Based Services is via the JavaScript Client Library, which provides graphical UI support for rendering maps, zooming, and showing routes and POI (Points of Interest) markers. Start here for a tutorial on the JavaScript Client Library for the Location Based Services.
Using the REST Interface means the app will retrieve data without graphical rendering; the developer needs to provide the graphical rendering of data themself. Some APIs provided by the REST Interface are not yet supported by the JavaScript Client Library. These include the GeoFencing, GeoMessaging, and Subscription APIs. (These APIs will be supported by a future release of the JavaScript Client Library.)
Overview
Note: The version number in the base URL for Location Based Services has changed from "/v1" to "/v2". You must update the base URLs in your existing apps to use the new features of Location Based Services. (There is a corresponding change for the JavaScript Client Library.)
The following list provides basic information to help implement the API calls:
- Developers must have an Intel® Identity Services account to obtain a Client ID and Client Secret for their location-aware app. This account information is used to identify developers and is used for billing/payments.
- Some calls require the user to have an Intel Identity Services account and to have given permission to your app to access their information. Guidance to help user's create their accounts is provided in the End User Signup Tutorial.
- The app must have the Context Services enabled (via your Developer Dashboard) for the Get POI call to return enhanced results.
- The application must place the access token for the Location session in the http header (or in the URI) prior to executing each call.
- The Location Based Services return response status for each call in the HTTP response value found in the header. More detailed response information is in the body. Responses are in JSON format only at this time.
- Multiple concurrent sessions for an application are supported. Each session will use a unique access token obtained when that session is started. The application is responsible for keeping track of the access tokens and their proper association with the sessions.
- For user authorization, the primary and secondary languages are set by appending the "language1=xx" and "language2=xx" parameters to the end of the first Location Based Service API call the app makes after authorization. While the first call can be any API call, you probably want to use the Get Map Attribution call since it is needed to populate the app's About box.
Supported Languages
| Value | Language |
|---|---|
| de | German |
| en | English |
| fr | French |
| he | Hebrew |
| it | Italian |
| es | Spanish |
- The languages assigned when the session is started are used as the base languages throughout the session. While these base languages cannot be changed during the session, the Search POI Request, Search Route Request, and Get Encrypted Static Map URL calls can optionally override the base languages for one call invocation.
Note: Because tokens are long, in API calls we usually substitute {access_token} or {refresh_token} for the real tokens. For calls that include elements like Client ID, Client Secret, and User ID, we usually substitute {client_id}, {client_secret}, and {user_id} for the real elements. In some cases, like initial use, we may show the real token or element. An example access token is shown below:
2/gAAAAB-gK_mJ8IW5-PQX8LkMkHXAl4viM0vRppECIkBVmfR1SOeQgvhLQnQzrwWKnbbsW1AKBzKss6eD0H3p0HMtIwtbgFQpeiqf0hDUEQlXTbt4UpKphIcV95Gc0C3PtkgNboV1TLGCC_bu5gLFXQJGAhmB6lkcJ5UwHGyn8BxFoayTdAEAAIAAAACDjEGPraEwMdWDz5MHNkulggsPdX41i4dMrdVcQdSBOcAP9vt9n0GwVNnJljsSCOH4UNHjosPpm7iwcOfF_4i_4InxRa-jRC0RWJWMxk9Xl-Uhtdv9WlxMgNZeSr5t9ySKCtREeCxYEBI1qwrnAy4a4zZMaXAevtiXx41T7IQGu3QV2oq_4etvssMPhokSYkRAhk_nSz9dcThH2u8w-NXZl3av-rS9eiGaVxQvqqmRG79F1iw-fu5frOirJSLEofvc9nlGGZOEMk53tCsiRuP8rJOqaBJsOuPWN5widmNlirKuMjkXTVShAaw-j03zMS4L39P3iuY-d9zLZUpyP3zh9poaRGEUKU5UXayGZIk76HcSsZBriPjV_84prhbh93F83XkWSOcWk1uwU_5GLPP2vu0VRxTuU_G4d1a3-aIjxE0T_OuFVSY0Lw5aAH2urUCljxbU8XDhKaOG8fi1-_HwII-5v-zLit83yy3QbOEFQ
All applications must authorize with Intel Cloud Services Platform before they can execute calls. A basic introduction to authorization for the Location Based Services is provided in the Intel Cloud Platform Services Location Based Services REST Developer's Guide. If you want to learn about authorization from a broader perspective, see the Intel Cloud Platform Services REST Authorization Overview.
Location Based Service Call Groups
The following table groups and summarizes the Location Based Service REST interface calls:
Location Based Service REST Interface Call Groups
| Management | |
|---|---|
| Call | Description |
| Get Map Attribution | Returns map provider information for the application's About box. |
| Enumeration | |
| Call | Description |
| Get Country List | Returns a list of supported countries for use in subsequent Geographical calls. |
| Get POI Categories | POI (Points of Interest) categories and a schema to hold POI information for use in subsequent POI calls. |
| Map | |
| Call | Description |
| Get Encrypted Static Map URL | Returns an encrypted URL for a static map within the geographic boundaries specified by the call. This encrypted URL can be embedded in image tags on web pages to provide a static (no panning, zooming, etc.) map. |
| Geographical | |
| Call | Description |
| Get POIs | Returns points of interest for the geographical area and the list of POIs in the call. When a user is logged in, POI information returned contains richer content; also, POI queries can be saved for later use. |
| Get Geocode (Address) | Returns coordinates based on the full or partial address specified in the call. |
| Get Reverse Geocode | Returns an address for the geographical coordinates specified in the call. |
| Get Route | Returns a path between the origin and destination coordinates in the call. Preferences and avoids can be specified in the call. When a user is logged in, Route queries can be saved for later use. |
| History (for Logged-In Users) | |
| Call | Description |
| Get Saved History | Returns saved POI or Route queries that were made for logged-in users to allow their searches to be saved and used to personalize future results. |
| GeoFencing and GeoMessaging (for Logged-In Users) | |
| Create GeoFence | Creates a GeoFence using the information in the call. |
| Get GeoFence | Retrieves the information for the specified GeoFence. |
| Get Multiple GeoFences | Retrieves the information for the all GeoFences for the user. |
| Delete GeoFence | Deletes the specified GeoFence. |
| Create GeoMessage | Creates a GeoMessage for the specified GeoFence using the message information in the call. |
| Get GeoMessage | Retrieves the information for the specified GeoMessages. |
| Get Multiple GeoMessages | Retrieves the information for multiple GeoMessages for the user. |
| Update GeoMessage | Updates the specified GeoMessage using the message information in the call. |
| Delete GeoMessage | Deletes the GeoMessage specified in the call. |
| Get GeoMessage Subscription | Retrieves message subscriptions and/or messages of the specified subscription type(s). |
| Update GeoMessage Subscription | Updates a subscription relationship for GeoMessages from a specific message publisher. |
For information on obtaining access tokens to execute calls, see the Intel Cloud Platform Services Location Based Services REST Developer's Guide.
Basic Location Calls
These calls in this section provide basic location based services to applications.
Map Attribution
Note: The base URL for all calls in this document points to the Test environment (:8081 in the path). You need to change your base URL when moving your app to Production.
Returns text identifying the companies providing maps for the specified geographical area.
Note: Maps provided by the Location Based Services may come from more than one map provider. The Cloud Services Platform beta License Agreement requires that applications display map provider attributions in the About box. This call allows developers to access the names of map providers to provide legal recognition and credit to them. Developers must still implement the code that displays this information in the About Box.
URL Structure
https://api.intel.com:8081/location/v2/map/attribution?access_token={access_token}
&lower_left_lat={lower_left_lat}&lower_left_lng={lower_left_lng}
&upper_right_lat={upper_right_lat}&upper_right_lng={upper_right_lng}
&alt={alt}
(Alternate) Header: Bearer {access_token}
Method: GET
Parameters
| Parameters | Required? | Input Type | Description |
|---|---|---|---|
| access_token | Yes | URI or Request header | Unique access token to identify the session and as proof of prior authorization during the current session. |
| lower_left_lat | Yes | URI | Left lower corner latitude of a bounding box for the requested map provider information. |
| lower_left_lng | Yes | URI | Left lower corner longitude of a bounding box for the requested map provider information. |
| upper_right_lat | Yes | URI | Right upper corner latitude of a bounding box for the requested map provider information. |
| upper_right_lng | Yes | URI | Right upper corner longitude of a bounding box for the requested map provider information. |
| alt | No | URI | This release of the Location Based Services supports JSON response only. |
Example Usage
GET
https://api.intel.com:8081/location/v2/map/attribution?access_token={access_token}
&lower_left_lat=51.46776&lower_left_lng=-0.17147039&upper_right_lat=51.53984
&upper_right_lng=-0.051680893&alt=json
(Alternate) Header: Bearer {access_token}
JSON Response
{
"data": {
"mapAttribution": "Telmap, © 2006-2013 TomTom"
}
}
Notes
- None at present.
Get Country List
Returns a list of supported countries.
URL Structure
https://api.intel.com:8081/location/v2/countries?access_token={access_token}
&list_mode={list_mode}&alt={alt}
(Alternate) Header: Bearer {access_token}
Method: GET
Parameters
| Parameters | Required? | Input Type | Description |
|---|---|---|---|
| access_token | Yes | URI or Request header | Unique access token to identify the session and as proof of prior authorization during the current session. |
| list_mode | No | URI | Requests a list of supported countries for the current user (ALL_USER_COUNTRIES), or a list of all the countries the backend mapping services supports (ALL_SERVER COUNTRIES). ALL_USER_COUNTRIES is the default if this parameter is not included. This parameter is case-sensitive and must be used exactly as shown. |
| alt | No | URI | This release of the Location Based Services supports JSON response only. |
Example Usage
GET
https://api.intel.com:8081/location/v2/countries?access_token={access_token}
&list_mode=ALL_USER_COUNTRIES&alt=json
(Alternate) Header: Bearer {access_token}
JSON Response (partial country list only)
{
"data": {
"kind": "country",
"items": [
{
"countryCode": {
"code": "SK"
},
"countryName": {
"text": "Slovenska Republika"
}
},
{
"countryCode": {
"code": "AD"
},
"countryName": {
"text": "Andorra"
}
},
{
"countryCode": {
"code": "GR"
},
"countryName": {
"text": "Ellada"
}
},
{
"countryCode": {
"code": "CAPE"
},
"countryName": {
"text": "PE, Canada"
}
},
{
"countryCode": {
"code": "USPA"
},
"countryName": {
"text": "PA,USA"
}
},
{
"countryCode": {
"code": "USOR"
},
"countryName": {
"text": "OR,USA"
}
},
{
"countryCode": {
"code": "CAON"
},
"countryName": {
"text": "ON, Canada"
}
},
{
"countryCode": {
"code": "ZA"
},
"countryName": {
"text": "South Africa"
}
}
]
}
}
Notes
- Country codes for most countries are 2-characters long. Country+state/province/territory codes are 4-characters long. At the time of publication, the Country list includes states/provinces/territories for the United States, Canada, and Australia; state/province information is not included for the remaining countries.
- ALL_USER_COUNTRIES is the recommended default for applications, as this helps protect against accidental access to/from countries that may be the subject of geopolitical prohibitions.
Get POI Categories
Returns a list of POI (Points of Interest) categories, within a schema for POI data, supported by the Location Based Services REST API.
See the POI Schema for a full schema listing.
URL Structure
https://api.intel.com:8081/location/v2/poi/categories?access_token={access_token}&alt={alt}
(Alternate) Header: Bearer {access_token}
Method: GET
Parameters
| Parameters | Required? | Type | Description |
|---|---|---|---|
| access_token | Yes | URI or Request header | Unique access token to identify the session and as proof of prior authorization during the current session. |
| alt | No | URI | This release of the Location Based Services supports JSON response only. |
Example Usage
GET
https://api.intel.com:8081/location/v2/poi/categories?access_token={access_token}&alt=json
(Alternate) Header: Bearer {access_token}
JSON Response
The JSON response is too long to show here. See the POI Schema for the full JSON schema listing.
Notes
- The following table lists the POI Category responses the app can receive.
Deprecated POI Categories
The POI Categories listed below are deprecated. Use the POI Categories listed in the Supported POI Categories table instead.
| POI Categories | Description |
|---|---|
| poi_hotels | Deprecated. Use "hotels" from the table below. |
| poi_gas_stations | Deprecated. Use "gas_station" from the table below. |
| poi_parking | Deprecated. Use "parking" from the table below. |
| poi_restaurants | Deprecated. Use "restaurants" from the table below. |
| poi_shopping | Deprecated. Use "shopping" from the table below. Or use the more specific shopping categories below. |
| poi_tourism | Deprecated. |
| poi_entertainment | Deprecated. Use "entertainment" from the table below. Or use the more specific entertainment categories below. |
| poi_transportation | Deprecated. Use "transportation' from the table below. Or use the more specific transportation categories below. |
| poi_emergency | Deprecated. |
| poi_community_services | Deprecated. |
Supported POI Categories
| POI Categories | Description |
|---|---|
| atm | Automated teller machine |
| gas_station | Gas station |
| hospital | Hospital |
| pharmacy | Pharmacy |
| police | Police station |
| restaurants | Restaurants |
| cinema | Movie theater |
| coffee_shop | Coffee shop |
| coffee | A business that sells coffee and other light foods, including pastries and other snacks. Inclusion - All major chain coffee shops (e.g., Starbucks), locally owned coffee shops, drivethru coffee stands, and tearooms that provide coffee as a primary service. |
| nightlife | An establishment that provides social activities or entertainment that is available in the evening. Inclusion - Bars, pubs, live music clubs, dance clubs, pool halls, arcades, karaoke, and standup comedy clubs. |
| amusement_park | A park that contains rides or other entertainment that may be based on a central theme. Inclusion – Major amusement parks that are regionally known. Miniature golf courses, go-cart raceways, and aquatic parks with wavepools and/or waterslides. |
| auto_service | Auto service establishment |
| banks | Bank |
| bookstore | Bookstore |
| bus_station | Bus station |
| commuter_rail | A facility established to provide regional or intra-city rail transportation. Inclusion – Metro Rail, Subway. NOTE: In Russia, only the Metro stations are included for Commuter Rail Station POIs. The regional trains are included under the Train Station category. |
| electronics_store | A business establishment that sells consumer electronics and electronic entertainment equipment. |
| ferry | Ferry |
| grocery_store | Grocery store |
| ice_skating | A facility designated for all types of ice skating. Inclusion – All indoor and outdoor ice skating rinks. |
| museum | Museum |
| recreation_area | An area of public land preserved and maintained for recreational use. Inclusion – Public parks and recreation areas. Named and unnamed beaches. |
| schools | Schools |
| sports_centre | A facility designated for recreational sports. Inclusion – All combined sport centers, swimming and tennis facilities, thermal baths, and famous public fitness centers that also offer other facilities like sauna and massage. |
| train_station | Train station for regional trains. |
| wineries | Wineries |
| worship | A building where religious services are held. Inclusion – All mosques, churches, temples, synagogues, ashrams, and other buildings where religious services are held. Not included: Temporary places of worship. For example, in Middle Eastern countries, mosques are sometimes temporary structures that exist to serve people at a location, such as a construction site, for a limited period of time. |
| post_office | Post office |
| bars | Bars |
| hardware_store | A retail establishment that sells a variety of building materials, hardware, and home improvement products. Inclusion – All locations fitting the definition are included. |
| airport | Airport |
| parking | Parking |
| rest_areas | A public facility, located next to a large thoroughfare such as a highway, expressway, freeway, or provincial road at which drivers and passengers can rest, eat, or refuel without exiting onto secondary roads. Inclusion – Any signed/named rest areas or scenic overlooks with parking along motorways and non-motorways. |
| tourist | Contains Tourist Attraction + Tourist Information Inclusion – Regionally known landmarks that do not meet the criteria for another more specific category (e.g., Eiffel Tower, zoos, and missions) + all tourist information offices. |
| hotels | Hotels |
| entertainment | Contains Cinema, Performing Arts, Nightlife, Casino Inclusion – All cinemas with more than 200 seats or multiple screens. Not included: Adult cinemas. / Cultural centers, concert halls, and theatres that seat more than 250 people, or that are locally known. / Any variety of gambling and gaming establishments ranging from the large casinos in Las Vegas to riverboat gambling and card rooms of regional draw such as the Bay 101 Club in San Jose. In Europe only those that are licensed by the government are included. |
| shopping | Contains Shopping, Clothing Store, Department Store, Home Specialty Store, Sporting Goods Store, Specialty Store Inclusion – Large retail stores carrying a wide variety of merchandise and organized into various departments for sales and administrative purposes. All shopping malls of regional importance and major outlet malls. All covered shopping centers, pedestrian areas and famous shopping streets with shops and restaurants. Major retail brands that are individual stores, usually located in shopping areas/boulevards. Inclusion is based on merchant sourced list. NOTE: In France, out-of-town shopping centers that typically comprise large furniture stores, carpet warehouses, and home improvement stores are also included. |
| transportation | Contains Train Station, Commuter Rail Station, Bus Station, Ferry Terminal, Transportation Service Inclusion – All facilities that function as a hub for passengers and goods travelling between metropolitan areas along a railway network. / All metro stations in the UK. |
| golf_course | Golf courses |
| synagogue | Synagogue |
| bowling_centre | Bowling centers |
| home_speciality | Furniture stores, do-it-yourself stores, stores that offer home improvement. |
| specialty_store | A business that specialises in the retail of a specific type of merchandise. Inclusion – Global: Stores that do not fit into one of the other shopping-related POI categories. North America: Wine and liquor stores are supplied by a third-party data supplier. |
| sporting_goods | A retail business that sells items used in team and individual sports including recreational sports. Inclusion – All locations fitting the definition are included. |
| underground | Metro in UK. Subway in US. |
| taxi | Taxi locations |
| nightclubs | Nightclubs |
| swimming_pools | Swimming pools |
| theaters | Theaters |
| doctors_clinics | Doctor's clinics |
- The schema for the categories is returned in the JSON response. The app uses the schema to build its own data structures in preparation for POI searches. The entire schema is too long to show here, but you can see the POI Schema here. Note that restaurants and hotels categories have a unique data structure (categoryAttributes), in addition to the standard structure, to support tailored enhanced information for user authorization searches on those categories.
- The reserved keyword "poi_all" is not returned in the response, but may still be used in POI Searches to return information for all POI categories.
Get POIs
Returns a list of POIs (Points of Interest) for the geographical area and preferences in the call.
Search results for non-logged in users (application authorization) return basic information (e.g., location, name, phone number, etc.), while enhanced fields will be null.
Search results for logged in users (user authorization) return enhanced fields that can contain additional attributes for restaurants and hotels categories. These enhanced categories are only valid for the United States at this time. These enhanced fields can be of great value to users (to match with their interests) and to developers (to personalize future results based on user preferences and past history). Note that the app must have the Context Services enabled (via your Developer Dashboard) for the Get POI call to return enhanced results.
Note: If a user is logged into their Intel Identity Services account and has approved sharing their information with the Location Based Services, POI queries are automatically saved for retrieval later (using the Get Search History call) and to personalize future search results.
URL Structure (using a centerpoint and radius)
https://api.intel.com:8081/location/v2/poi?access_token={access_token}&lat={lat}&lng={lng}
&radius={radius}&category={category,category,category}&time_hint={time_hint}&name={name}
&num_results={num_results}&offset={offset}&language1={language}&alt={alt}
(Alternate) Header: Bearer {access_token}
Method: GET
URL Structure (using a bounding box)
https://api.intel.com:8081/location/v2/poi?access_token={access_token}&lower_left_lat={lower_left_lat}
&lower_left_lng={lower_left_lng}&upper_right_lat={upper_right_lat}
&upper_right_lng={upper_right_lng}&category={category,category,category}&time_hint={time_hint}&name={name}
&num_results={num_results}&offset={offset}&language1={language}&alt={alt}
(Alternate) Header: Bearer {access_token}
Method: GET
Parameters
| Parameters | Required? | Input Type | Description |
|---|---|---|---|
| access_token | Yes | URI or Request header | Unique access token to identify the session and as proof of prior authorization during the current session. |
| *Must include either lat/lng/radius or left/right bounding box | |||
| lat | Yes* | URI | Center point latitude; used with lng and radius instead of a bounding box. |
| lng | Yes* | URI | Center point longitude; used with lat and radius instead of a bounding box. |
| radius | Yes* | URI | Radius in meters; used with lng and lat instead of a bounding box. |
| lower_left_lat | Yes* | URI | Left lower corner latitude of a bounding box for the requested list. |
| lower_left_lng | Yes* | URI | Left lower corner longitude of a bounding box for the requested list. |
| upper_right_lat | Yes* | URI | Right upper corner latitude of a bounding box for the requested list. |
| upper_right_lng | Yes* | URI | Right upper corner longitude of a bounding box for the requested list. |
| category | No | URI | Indicating POI filter to apply to the search, e.g., shopping. The reserved keyword poi_all, may also be used to get results for all categories. (Multiple categories can be searched in a call by including the category names separated by commas. When both category and name are included, only name is used. When neither are included, "category=poi_all" is the default.) |
| name | No | URI | Value indicating name of a business or other points of interests. Examples: "atm", "pub", etc. (When both category and name are included, only name is used. When neither are included, "category=poi_all" is the default.) |
| time_hint | No | URI | Current time in UTC format. Provided by the application and intended to represent the actual time on the user's device. Used by the services to provide more meaningful results where time may be a relevant factor (e.g., breakfast vs. dinner restaurants). Only used for logged-in users. |
| num_results | No | URI | The number of results to retrieve in the response. The default is 15 if this parameter is not specified. This parameter requests a list of up to num_results items from a potentially larger list. See the "maxResultsAvailable" response and the "offset" parameter on how to request more items from a long list. |
| offset | No | URI | The offset within the results. The default is zero when no offset is specified. |
| language1 | No | URI | Language for response results; overrides base languages specified at session creation for current call only. |
| alt | No | URI | This release of the Location Based Services supports JSON response only. |
Example Usage
Using a centerpoint and radius
GET
https://api.intel.com:8081/location/v2/poi?access_token={access_token}&lat=45.21&lng=-118.43
&radius=45&category=restaurants&time_hint=2013-01-29T15:00:31Z&num_results=10&offset=0&alt=json
Alternate) Header: Bearer {access_token}
Using a bounding box
GET
https://api.intel.com:8081/location/v2/poi?access_token={access_token}&lower_left_lat=45.21
&lower_left_lng=-118.43&upper_right_lat=45.23&upper_right_lng=-118.45&category=POI_ALL
&name=atm&num_results=6&offset=0&alt=json
Alternate) Header: Bearer {access_token}
Using a centerpoint and radius with multiple categories
GET
https://api.intel.com:8081/location/v2/poi?access_token={access_token}&lat=45.21&lng=-118.43
&radius=45&category=restaurants,hotels,nightclubs&time_hint=2013-01-29T15:00:31Z&num_results=10&offset=0&alt=json
Alternate) Header: Bearer {access_token}
JSON Response
Response will vary depending on the category of the POI. When multiple POI category types are returned, each POI will indicate its type within that POI's structure.
The following tables list the categoryAttributes fields for the Restaurants and Hotels categories.
Restaurants Enhanced Fields
| Name | Type | Description |
|---|---|---|
| cuisine | String | One or more comma-delimited strings describing the kind of food served. |
| price | String | A price metric. Enum: ["$","$$","$$$","$$$$","$$$$$"]. |
| hours | Object | Restaurant hours of operation. |
| status | String | Indicates the status of the POI. Enum: ["closed","open"]. |
| rating | Integer (1 to 5) | Restaurant rating. |
| overview | String | Long human-readable description of the POI. |
| reservations | Boolean | Accepts reservations. |
| parking | Boolean | Some kind of parking is available. |
| seatingOutdoor | Boolean | Outdoor seating is available. |
| Wi-Fi | Boolean | WiFi* is provided by the establishment. |
| paymentCashOnly | Boolean | Only accepts cash. |
| creditCardsAccepted | String | List of credit cards accepted by this business. |
| alcohol | Boolean | Alcohol is served or can be consumed on the premises. |
| smoking | Boolean | Indicates if someprovision for smoking is available. |
| mealBreakfast | Boolean | Breakfast is served. |
| mealLunch | Boolean | Serves lunch. |
| mealDinner | Boolean | Serves dinner. |
| mealDeliver | Boolean | Makes deliveries. |
| optionsOrganic | Boolean | Organic food is served. |
| optionsLowfat | Boolean | Low-fat food is available. |
| optionsVegetarian | Boolean | Vegetarian dishes are served. |
| optionsHealthy | Boolean | Healthy dishes are served. |
| kidsGoodFor | Boolean | Noted as being good for kids. |
| groupsGoodFor | Boolean | Noted as being good for groups. |
| accessibleWheelchair | Boolean | Premises are accessible by wheelchair. |
| hours | Object | List of 7 days and open hours for each day. |
Hotels Enhanced Fields
| Name | Type | Description |
|---|---|---|
| stars | Integer | Hotel stars (from 1 to 5). |
| price | String | A price metric. Enum: ["$","$$","$$$","$$$$","$$$$$"]. |
| overview | String | Overview description. |
| parking | Boolean | The hotel has some kind of parking space. |
| freeBreakfast | Boolean | The hotel offers free breakfast. |
| roomService | Float | The hotel offers room service. |
| fitnessCenter | Boolean | The hotel has a fitness center. |
| businessCenter | Boolean | The hotel has a business center (work space with computers, printers, meeting place, etc.). |
| freeInternet | Boolean | The hotel offers free Internet. |
| petsAllowed | Boolean | The hotel allows pets. |
| accessibleWheelchair | Float | The hotel has wheelchair access. |
| currenciesAccepted | String | One or more comma-delimited strings describing the currencies accepted (in ISO 4217 currency format). |
| branchOf | String | The larger organization that this local business is a branch of, if any. |
| Hours | Object | Opening hours (representing check-in/checkout hours). |
Other Categories / All Categores
Note: The listing below uses Gas Stations as an example; the same fields are also used for all other categoreis.
JSON Response (using gas_stations structure)
{
"id": "poi_gas_stations",
"label": "Gas Station",
"labelPlural": "Gas Stations",
"description": "A gas station",
"version": "1.0.0.0",
"fields": [
{
"name": "id",
"label": "Id",
"description": "",
"dataType": "string",
"searchable": false,
"sortable": false
},
{
"name": "category",
"label": "Category",
"description": "",
"datatype": "string",
"searchable": true,
"sortable": false
},
{
"name": "name",
"label": "Name",
"description": "",
"datatype": "string",
"searchable": true,
"sortable": false
},
{
"name": "latitude",
"label": "Latitude",
"description": "",
"datatype": "number",
"searchable": true,
"sortable": false
},
{
"name": "longitude",
"label": "Longitude",
"description": "",
"datatype": "number",
"searchable": true,
"sortable": false
},
{
"name": "country",
"label": "Country",
"description": "",
"datatype": "string",
"searchable": false,
"sortable": false
},
{
"name": "state",
"label": "State",
"description": "",
"datatype": "string",
"searchable": false,
"sortable": false
},
{
"name": "city",
"label": "City",
"description": "",
"datatype": "string",
"searchable": false,
"sortable": false
},
{
"name": "streetAddress",
"label": "StreetAddress",
"description": "",
"datatype": "string",
"searchable": false,
"sortable": false
},
{
"name": "website",
"label": "Website",
"description": "",
"datatype": "string",
"searchable": false,
"sortable": false
},
{
"name": "phone",
"label": "Phone",
"description": "",
"datatype": "string",
"searchable": false,
"sortable": false
},
{
"name": "email",
"label": "Email",
"description": "",
"datatype": "string",
"searchable": false,
"sortable": false
},
{
"name": "weight",
"label": "Weight",
"description": "",
"datatype": "number",
"searchable": false,
"sortable": false
}
]
}
Notes
- Enhanced results for the US can include the Restaurants and Hotels categories.
- POI information for logged-in vs. non-logged in users come from different information sources. Therefore, POI search results for logged-in users and non-logged in users can vary, even for the same geographic area.
- When both category and name are included, only name is used. When neither are included, "category=poi_all" is the default.
- Bounding boxes where one or more corners lie in a large body of water will return empty results.
- If the target area for a POI search occurs for an unpopulated region (such as a desert/mountain area or a body of water), the basic_poi response is returned, even for cases where an enhanced_poi structure would otherwise be returned.
- When using the time_hint parameter, if the time format (UTC) is not correct the POI query is not saved and therefore cannot be retrieved later.
Subsequent Invocation Example
GET
https://api.intel.com:8081/location/v2/poi?access_token={access_token}&lower_left_lat=45.21&lower_left_lng=-118.43
&upper_right_lat=45.23&upper_right_lng=-118.45&category=POI_ALL&num_results=10&offset=1&alt=json
(Alternate) Header: Bearer {access_token}
Get Geocode (Address)
Returns coordinates based on the full or partial address specified in the call.
URL Structure
https://api.intel.com:8081/location/v2/geocode?access_token={access_token}
&country_code={country_code}&city={city}&street={street}
&number={number}&junction_street=(junction_street}
&postal={postal}*full_address{full_address}&num_results={num_results}
&offset={offset}&alt={alt}
(Alternate) Header: Bearer {access_token}
Method: GET
Parameters
| Parameters | Required? | Input Type | Description |
|---|---|---|---|
| access_token | Yes | URI or Request header | Unique access token to identify the session and as proof of prior authorization during the current session. |
| country_code | Yes | URI | Country code as specified in ISO-3166: 2-letter format for supported countries. For the United States, Canada, and Australia, a 4-letter code is supported that reflects the country and state/province/territory, e.g., USNY for United States – New York. (For the United States, the 2-letter code can be used to search outside a specific state.) |
| city | No | URI | City name, e.g., Dallas. |
| street | No | URI | Street name, e.g., Cherry Ln. |
| number | No | URI | Address, e.g., 1124. |
| junction_street | No | URI | Intersection or joining street. |
| postal | No | URI | Postal code. |
| full_address | No | URI | Single line representing a partial or entire address to search on. When specified, the information in this string overrides the information in the other address strings (except country_code). |
| num_results | No | URI | The number of results to retrieve in the response. The default is 15 if this parameter is not specified. This parameter requests a list of up to num_results items from a potentially larger list. See the "maxResultsAvailable" response and the "offset" parameter on how to request more items from a long list. |
| offset | No | URI | The offset within the results. The default is zero when no offset is specified. |
| alt | No | URI | This release of the Location Based Services supports JSON response only. |
Example Usage
Search within a state (United States, Colorado)
GET
https://api.intel.com:8081/location/v2/geocodeaccess_token={access_token}&country_code=USCO&city=Denver
&street=Ashland&junction_street=Caldwell&postal=78643&num_results=10&offset=0&alt=json
Alternate) Header: Bearer {access_token}
Search outside a single state (United States)
GET
https://api.intel.com:8081/location/v2/geocodeaccess_token={access_token}&country_code=US&city=Hillsboro
&street=25th&num_results=10&offset=0&alt=json
Alternate) Header: Bearer {access_token}
JSON Response
{
"data": {
"items": [
{
"countryName": {
"text": "OR,USA"
},
"city": {
"text": "Hillsboro"
},
"street": null,
"houseNumber": null,
"jctStreet": null,
"postcode": null,
"boundingBox": {
"lowerLeft": {
"latitude": 45.3631,
"longitude": -123.0761
},
"upperRight": {
"latitude": 45.65369,
"longitude": -122.85938
}
},
"countryCode": {
"code": "USOR"
},
"description": {
"text": "Hillsboro, OR"
},
"geoPoint": {
"latitude": 45.5227,
"longitude": -122.99056
},
"mapWidthInMeters": -1
}
]
}
}
Notes
- When only a partial address is provided in the call, the response may provide a list of possible addresses. The application can present the list to the user to allow them to narrow down a more specific location.
- Approximate string matches are provided where a complete string has not been included or where possibly misspelled names are included.
- Responses may also contain the moreLocationsAvailable boolean. When “moreLocationsAvailable=true”, the response indicates that more entries are available. Subsequent instances of this call can be made to obtain the remaining contents of the Address list using the offset parameter. A second invocation is shown below as indicated by “offset=1”.
Subsequent Invocation
GET
https://api.intel.com:8081/location/v2/geocode?access_token={access_token}country_code=USCO&city=Denver
&street=Ashland&junction_street=Caldwell&postal=78643&num_results=10&offset=1&alt=json
(Alternate) Header: Bearer {access_token}
Get Reverse Geocode (Address)
Returns an address based on the geographical coordinates specified in the call.
URL Structure
https://api.intel.com:8081/location/v2/reversegeocode?access_token={access_token}&lat={lat}&lng={lng}&alt={alt}
(Alternate) Header: Bearer {access_token}
Method: GET
Parameters
| Parameters | Required? | Input Type | Description |
|---|---|---|---|
| access_token | Yes | URI or Request header | Unique access token to identify the session and as proof of prior authorization during the current session. |
| lng | Yes | URI | Longitude for the requested location. |
| lat | Yes | URI | Latitude for the requested location. |
| alt | No | URI | This release of the Location Based Services supports JSON response only. |
Example Usage
GET
https://api.intel.com:8081/location/v2/reversegeocode?access_token={access_token}&lat=45.21&lng=-118.43&alt=json
(Alternate) Header: Bearer {access_token}
JSON Response
{
"data": {
"location": {
"countryName": {
"text": "United Kingdom"
},
"city": {
"text": "London"
},
"street": {
"text": "Duke Street St James's"
},
"houseNumber": null,
"jctStreet": null,
"postcode": null,
"boundingBox": {
"lowerLeft": {
"latitude": 51.50657,
"longitude": -0.1388
},
"upperRight": {
"latitude": 51.50844,
"longitude": -0.13708
}
},
"countryCode": {
"code": "GB"
},
"description": {
"text": "Duke Street St James's, St James's, Sw1, London, United Kingdom"
},
"geoPoint": {
"latitude": 51.5071,
"longitude": -0.137565
},
"mapWidthInMeters": -1
}
}
}
Notes
- The call returns an error if the coordinates identify a point greater than 200 meters from a known street.
- If the geographic location specified is in a large body of water, the address information in the response will be empty.
Get Route
Returns a path (directions) between the origin and destination coordinates in the call.
Note: If a user is logged into their Intel Identity Services account and has approved sharing their information with the application, Route queries are automatically saved for retrieval later using the Get Search History call. Over time, Route queries that include some POIs can influence the "weight" of later POI queries. For example, if a Restaurant POI has enhanced information available (such as cuisine and price information) and appears in multiple Route queries, that history can influence subsequent POI query results for Restaurants in the same geographic area. That is, the "weight" field for that Restaurant POI in the JSON response will be higher than the initial default of 0. Applications can use this weighting to provide more personalized results to end users.
URL Structure
https://api.intel.com:8081/location/v2/route?access_token={access_token}&origin_lat={origin_lat}
&origin_lng={origin_lng}&destination_lat={destination_lat}&destination_lng={destination_lng}
&route_algorithm={route_algorithm}&avoids={avoids}&measurement={measurement}&zoom={zoom}
&via_points_lat_lng={lat},{lng}&preferred={preferred}&time_hint={time_hint}&alt={alt}
(Alternate) Header: Bearer {access_token}
Method: GET
Parameters
| Parameters | Required? | Input Type | Description |
|---|---|---|---|
| access_token | Yes | URI or Request header | Unique access token to identify the session and as proof of prior authorization during the current session. |
| origin_lat | Yes | URI | Originating latitude point for route start. |
| origin_lng | Yes | URI | Originating longitude point for route start. |
| destination_lat | Yes | URI | Destination latitude point for route. |
| destination_lng | Yes | URI | Destination longitude point for route. |
| route_algorithm | No | URI | Type of algorithm to use for calculating route, e.g., FASTEST (driving) (default), SHORTEST (driving), PEDESTRIAN. These are case-sensitive parameters and must be entered exactly as shown. |
| avoids | No | URI | A list of road types to avoid, e.g., FERRY, HIGHWAY, TOLLWAY, UNPAVED. These are case-sensitive parameters and must be entered exactly as shown. |
| measurement | No | URI | Imperial or metric, e.g., METRIC (default), IMPERIAL, IMPERIAL_FEET. These are case-sensitive parameters and must be entered exactly as shown. |
| zoom | No | URI | The services uses this value to set the polyline simplification to reduce the number of points returned. |
| via_points_lat_lng | No | URI | Ensure route includes indicated coordinate points, e.g., (multiple) &via_points_lat_lng=lat1,lng1,lat2,lng2, ... |
| preferred | No | URI | A list of preferred road types, e.g., (multiple) &prefer=HIGHWAY,TOLLWAY, ... |
| time_hint | No | URI | Current time in UTC format. Provided by the application and intended to represent the actual time on the user's device. Used by the services to provide more meaningful results where time may be relevant factor (e.g., breakfast vs. dinner restaurants). Only used for logged-in users. |
| alt | No | URI | This release of the Location Based Services supports JSON response only. |
Example Usage
Using preferred and avoids
GET
https://api.intel.com:8081/location/v2/route?access_token={access_token}&origin_lat=45.21&origin_lng=-118.43
&destination_lat=45.23&destination_lng=-118.455&route_algorithm=FASTEST&avoids=FERRY&prefer=HIGHWAY&alt=json
(Alternate) Header: Bearer {access_token}
Using measurement and vias
GET
https://api.intel.com:8081/location/v2/route?access_token={access_token}&origin_lat=45.21&origin_lng=-118.43
&destination_lat=45.23&destination_lng=-118.45&measurement=METRIC&via_points_lat_lng=45.226,-118.445,
45.2283,-118.4467&alt=json
(Alternate) Header: Bearer {access_token}
JSON Response (partial listing)
{
"data": {
"origin": {
"latitude": 51.53371,
"longitude": -0.108795136
},
"destination": {
"latitude": 51.51584,
"longitude": -0.069191456
},
"overviewLocation": {
"boundingBox": {
"lowerLeft": {
"latitude": 51.51408,
"longitude": -0.11369125
},
"upperRight": {
"latitude": 51.53464,
"longitude": -0.066835
}
},
"countryCode": {
"code": ""
},
"description": null,
"geoPoint": {
"latitude": 51.52436,
"longitude": -0.09026313
},
"mapWidthInMeters": -1
},
"polylinePoints": [
{
"latitude": 51.53371,
"longitude": -0.108795136
},
{
"latitude": 51.53351,
"longitude": -0.10879
},
{
"latitude": 51.53346,
"longitude": -0.10937
},
{
"latitude": 51.53338,
"longitude": -0.1107
},
{
"latitude": 51.53333,
"longitude": -0.11146
},
{
"latitude": 51.53263,
"longitude": -0.11141
},
{
"latitude": 51.53218,
"longitude": -0.11133
},
{
"latitude": 51.53165,
"longitude": -0.11119
}
],
"items": [
{
"description": {
"text": "Go south on White Conduit Street for 30m"
},
"position": {
"latitude": 51.53371,
"longitude": -0.108795136
},
"type": "INST_ORIGIN",
"nextStreetName": {
"text": "White Conduit Street"
},
"distanceToNextTurnInMeters": 22,
"exitName": "",
"headingDirectionInDegrees": 179
},
{
"description": {
"text": "Turn right to Chapel Market, go 190m"
},
"position": {
"latitude": 51.53351,
"longitude": -0.10879
},
"type": "INST_RIGHT",
"nextStreetName": {
"text": "Chapel Market"
},
"distanceToNextTurnInMeters": 187,
"exitName": "",
"headingDirectionInDegrees": -1
},
{
"description": {
"text": "Turn left to Penton Street, go 190m"
},
"position": {
"latitude": 51.53333,
"longitude": -0.11146
},
"type": "INST_LEFT",
"nextStreetName": {
"text": "Penton Street"
},
"distanceToNextTurnInMeters": 188,
"exitName": "",
"headingDirectionInDegrees": -1
},
{
"description": {
"text": "Turn left to Pentonville Road, go 1.9km"
},
"position": {
"latitude": 51.53165,
"longitude": -0.11119
},
"type": "INST_LEFT",
"nextStreetName": {
"text": "Pentonville Road"
},
"distanceToNextTurnInMeters": 1839,
"exitName": "",
"headingDirectionInDegrees": -1
},
{
"description": {
"text": "At the roundabout, take the first turn, go 160m"
},
"position": {
"latitude": 51.525955,
"longitude": -0.087325364
},
"type": "INST_ROUNDABOUT_1",
"nextStreetName": {
"text": "Old Street"
},
"distanceToNextTurnInMeters": 158,
"exitName": "",
"headingDirectionInDegrees": -1
}
],
"totalDistanceInMeters": 4345,
"totalTimeSeconds": 809
}
}
Notes
- Pedestrian routes use different rules than driving routes, such as ignoring one-way streets and restricting access to highways.
- When using the time_hint parameter, if the time format is not correct (UTC) the Route query is not saved and therefore cannot be retrieved later.
- The following table shows the constants that can be used in various parameters to specify preferred route types, route types to avoid, etc. These parameters are case-sensitive and must be entered exactly as shown.
Route Request Constants
| Route Algorithm Types | |
|---|---|
| Constant | Description |
| FASTEST | Fastest route suitable for driving a car. |
| SHORTEST | Shortest route suitable for driving a car. |
| PEDESTRIAN | Route suitable for pedestrians. |
| Units of Distance | |
| Constant | Description |
| METRIC | Use meters and kilometers to describe distance. |
| IMPERIAL | Use miles to describe distance. |
| IMPERIAL_FEET | Use feet to describe distance. |
| Route Avoid/Preference Types | |
| Constant | Description |
| FERRY | Roads that require a ferry. |
| HIGHWAY | Highways. |
| TOLLWAY | Tollways. |
| UNPAVED | Unpaved roads. |
| IL_PA_A | (Israel only) |
| IL_PA_B | (Israel only) |
| IL_PA_C | (Israel only) |
Get Saved Search History (Queries)
For users who have approved sharing their information with the Location Based Services, this call returns a history of POI or Route queries that were previously saved.
Note: Only queries that were previously saved while the user was logged in are available for retrieval. Also, the user must have initially approved sharing their information with the app.
URL Structure
https://api.intel.com:8081/location/v2/searchhistory?access_token={access_token}&search_type={search_type}
&num_results={num_results}&offset={offset}&alt={alt}
(Alternate) Header: Bearer {access_token}
Method: GET
Parameters
| Parameters | Required? | Input Type | Description |
|---|---|---|---|
| access_token | Yes | URI or Request header | Unique access token to identify the session and as proof of prior authorization during the current session. |
| search_type | No | URI | The class of searches to be returned: POI, ROUTE, or ALL. ALL is the default if this parameter is not present. |
| num_results | No | URI | The maximum number of results to retrieve in the response. |
| offset | No | URI | The offset within the results. The default is zero when no offset is specified. |
| alt | No | URI | This release of the Location Based Services supports JSON response only. |
Example Usage
GET
https://api.intel.com:8081/location/v2/searchhistory?
access_token={access_token}&search_type=ALL
&num_results=20&offset=10&alt=json
(Alternate) Header: Bearer {access_token}
JSON Response
{
"data": {
"items": [
{
"value": {
"origin": {
"location": {
"latitude": 51.533707,
"longitude": -0.108795
},
"datetime": "2013-01-29T20:15:44Z"
},
"destination": {
"location": {
"latitude": 51.51571,
"longitude": -0.06955791
},
"datetime": "2013-01-29T20:15:44Z"
},
"trafficAware": false
},
"clientCreatedTime": "2013-01-29T20:15:44Z",
"contextType": "urn:x-intel:context:type:location:route",
"serverCreatedTime": "2013-01-29T20:16:06Z",
"provider": "92a9417f-3ac0-42a1-86da-c8c7dfc1ea21",
"owner": "4a9d17dd-a84e-4086-ac5b-f469ccabfae3",
"serverModifiedTime": "2013-01-29T20:16:06Z",
"id": "b69a8511-6a50-11e2-b7c8-000000000000"
},
{
"value": {
"source_domain": "Intel-Choices",
"type": "['restaurants']",
"name": "urn:x-intel:context:type:search",
"location": {
"latitude": 45.4,
"longitude": -122.6
}
},
"clientCreatedTime": "2013-01-29T12:06:39Z",
"contextType": "urn:x-intel:context:type:search",
"serverCreatedTime": "2013-01-29T18:07:01Z",
"provider": "92a9417f-3ac0-42a1-86da-c8c7dfc1ea21",
"owner": "4a9d17dd-a84e-4086-ac5b-f469ccabfae3",
"serverModifiedTime": "2013-01-29T18:07:01Z",
"id": "ae521075-6a3e-11e2-8e95-000000000000"
},
{
"value": {
"source_domain": "Intel-Choices",
"type": "['restaurants']",
"name": "urn:x-intel:context:type:search",
"location": {
"latitude": 45.5250485,
"longitude": -122.6750525
}
},
"clientCreatedTime": "2013-01-24T16:58:03Z",
"contextType": "urn:x-intel:context:type:search",
"serverCreatedTime": "2013-01-24T23:00:46Z",
"provider": "92a9417f-3ac0-42a1-86da-c8c7dfc1ea21",
"owner": "4a9d17dd-a84e-4086-ac5b-f469ccabfae3",
"serverModifiedTime": "2013-01-24T23:00:46Z",
"id": "e37b7621-6679-11e2-be09-000000000000"
}
]
}
}
Notes
- This call is only supported for user authorization.
Get Encrypted Static Map URL
Returns an encrypted static map URL for the geographic area and preferences specified in the call. This URL can be used in image tags on websites.
Note: This API does not provide dynamic rendering of maps (e.g., zooming, panning). Use the Location Based Services JavaScript Client Library if your app needs dynamic maps.
URL Structure
https://api.intel.com:8081/location/v2/staticurl?access_token{access_token}¢er={lat,lng}&zoom=(zoom)
&size={pixel_width}x{pixel_height}&markers={lat,lng}
&info_window={lat,lng}|text:{string}|size:{pixel_width}x{pixel_height}
&route=from:{lat,lng}|to:{lat,lng}|algorithm:{algorithm}
&language1={language}&alt={alt}
(Alternate) Header: Bearer {access_token}
Method: GET
Parameters
| Parameters | Required? | Input Type | Description |
|---|---|---|---|
| access_token | Yes | URI or Request header | Unique access token to identify the session and as proof of prior authorization during the current session. |
| size | Yes | URI | Size of the static map in pixels [ width x height ]. Static maps can range in size from 120 x 120 to 640 x 640. |
| *at least one of the following: center/zoom, markers, info_window, or route | |||
| center and zoom | Yes* | URI | Center of the static map in latitude and longitude. Zoom level ranging from 1 to 17. |
| markers | Yes* | URI | Markers for displaying on the static map. Only one Marker is currently supported. See "Markers" discussion below for parameter details. |
| info_window | Yes* | URI | Information window for displaying text on the static map. See "info_window" discussion below for parameter details. |
| route | Yes* | URI | Route for displaying on the static map. See the "Route" discussion below for parameter details. |
| dpi | No | URI | Pixel density of the static map. Range = 70 to 300 dpi. Default is 150 dpi. |
| show | No | URI | A list of locations to be guaranteed to be included in the map. These locations can automatically change the zoom level and framing of the map if necessary. No location is tagged on the map with a visible marker. Cannot appear with size or icon parameter for a given marker. |
| language1 | No | URI | Language for response results; overrides base languages specified at session creation for current call only. |
| alt | No | URI | This release of the Location Based Services supports JSON response only. |
Example Usage
GET
https://api.intel.com:8081/location/v2/staticurl?access_token{access_token}&size=480x480¢er=48.854,2.307
&zoom=13&markers=48.845,2.307&info_window=48.847,2.308|text:Eiffel Tower Travel|size:140x95
&route=from:48.874,2.293|to:48.845,2.307|algorithm:FASTEST&show=48.927,2.293|48.560,2.302|48.206,2.261
&language1=en&alt=json
(Alternate) Header: Bearer {access_token}
JSON Response
{
"data": {
"url": "http://api.intel.com/location/v2/staticmap?q=NMeUdoCOzRxShfWBESg6WIjz9BA
HXMPg6SvM5q6x0pUeOUe%2BlbWudiSwwy7fHUeVv7rsCT1eI0De4CDOk6XfzXgARWQ6Cdf32jGi%2FvjkMIBirtMmU7
3hvL4fP2KV72GGVMumsyyR%2BiTbqqSdHompBrbt22RmJhNEul6UeM4ML3c8IL%2BzvvEUYtkAN6lgI8AiY6irtOhnn
pxdIyFGulaGjXsmVwof9FLwVvnNst1dFKRcdcHQSTyJmdP%2FztjBh5iMawOukcL%2BvpGYRphAx9mmxA%3D%3D"
}
}
Then add the Get Static Map API URL in the response to your target web page so that each time the page is opened, the map is fetched and displayed.
GET
http://api.intel.com/location/v2/staticmap?q=NMeUdoCOzRxShfWBESg6WIjz9BA
HXMPg6SvM5q6x0pUeOUe%2BlbWudiSwwy7fHUeVv7rsCT1eI0De4CDOk6XfzXgARWQ6Cdf32jGi%2FvjkMIBirtMmU7
3hvL4fP2KV72GGVMumsyyR%2BiTbqqSdHompBrbt22RmJhNEul6UeM4ML3c8IL%2BzvvEUYtkAN6lgI8AiY6irtOhnn
pxdIyFGulaGjXsmVwof9FLwVvnNst1dFKRcdcHQSTyJmdP%2FztjBh5iMawOukcL%2BvpGYRphAx9mmxA%3D%3D
Markers
Markers are symbols used to call attention to specific locations. Parameters allow you to position one or more markers precisely on a map and to enable labels for the marker(s). You can substitute a custom marker image for the default pin marker image and precisely locate its tip. You can also specify invisible markers to ensure that specific locations are included in a map with no markers visible at those locations.
Parameter Example
&markers=48.845,2.307|size:small|label:true
&markers=48.874,2.293|icon:http://www.myxyzserver.com/bluesmileyicon.png|iconTip:200,200
Markers Parameters
| Parameters | Required? | Description |
|---|---|---|
| location | Yes | Location of a marker on the map. Values = latitude, longitude. |
| size | No | Size of the marker pin. Possible values: small, medium (or default), large Cannot appear with icon or show parameter for a given marker. |
| label | No | Label of the marker pin. Possible values: true (markers are labeled with ordered letters, e.g., A, B, C, ... Z, AA, BB, CC, etc.), false (no labels on markers), or string: Restricted to one uppercase letter; all additional characters are ignored. |
| icon | No | A URL to a picture to be used instead of the default pin icon. Used in combination with the iconTip parameter. Maximum picture size is 300 x 300 pixels. Cannot appear with size or show parameter for a given marker. Supported graphics formats: JPEG, PNG, BMP, WBMP, GIF. |
| iconTip | No | Exact position of the icon tip [ offsetX x offsetY ]. Used in combination with the icon parameter. Represents the number of pixels from the top left corner of the icon. |
Note the following behaviors of the Markers parameters and of markers:
- Only one Marker is currently supported.
- Parameters can appear in any order for a given marker.
- Actual marker size may change, depending on the DPI of the map.
- Spaces are not supported in icon pathnames or filenames.
- The .ico image format is not supported.
info_window
info_windows are text windows used to display information, such as a Point of Interest, business/service name, address, etc. Parameters allow you to position an info_window precisely on a map, either by itself or attached to a dedicated marker. You can also control aspects of the info_window presentation.
Parameter Example
&info_window=48.847,2.308|text:Eiffel Tower Travel|size:140x95|marker:true|style:sharp ...
info_window Parameters
| Parameters | Required? | Description |
|---|---|---|
| location | Yes | Location of info_window on the map. Values = latitude, longitude. |
| text | Yes | Text to display in the info_window. |
| size | Yes | Size of the info_window [ width x height ]. Size must be smaller than the map size and equal to or larger than the minimum size of 108 x 100 pixels. |
| marker | No | Manipulates the dedicated marker for the info_window. Possible values: false (for no marker; same as not using info_window marker parameter at all) true, medium or default (for medium marker), small (for a small marker), or large (for a large marker) |
| style | No | Style for attaching the info_window to its marker (assuming a marker is used). Possible values: sharp or default (for a single sharp tip that can "attach" to a marker), or round (for a rounded attachment that can "sit" on a marker) |
Note the following behaviors of the info_windows parameters and of info_windows:
- Parameters can appear in any order for a given info_window.
- If more than one location is specified for an info_window, the last location is used.
- The overall look and feel of the info_window image changes, depending on the DPI of the map.
Routes with Static Maps
Routes are paths between to specific locations and may contain preferences for how to travel the route. Parameters allow you to identify the starting and ending points, via points to pass along the way, route preferences (e.g., walking vs. driving), route avoids (e.g., tollways), and algorithm preferences (e.g., shortest or fastest).
Parameter Example
&route=from:48.874,2.293|to:48.845,2.307|via:48.40,2.312|weight:4|color:blue|avoid:TOLLWAY|algorithm:FASTEST ...
Route Parameters
| Parameters | Required? | Description |
|---|---|---|
| from | Yes | Starting point for the route. Values = latitude, longitude. |
| to | Yes | Ending point for the route. Values = latitude, longitude. |
| via | No | Points to route through along the way from the starting point to the ending point. Multiple via points are allowed, but all vias are interpreted as ordered between the starting point to the end point. Values = latitude, longitude. |
| weight | No | Weight of the route line in pixels. Values must be between 1 and 100. Default is 3. |
| color | No | Line color and transparency of the route line. Possible values: predefined colors {white, lightGray, gray, darkGray, black, red, pink, orange, yellow, green, magenta, cyan, blue} hexadecimal values: 24-bit (e.g., color:FF0096) and 32-bit (e.g., color:FF09652) When you specify a 32-bit value, the last two characters specify the 8-bit alpha transparency value. This value can range from 00 (completely transparent) to FF (completely opaque). |
| algorithm | No | Possible values: SHORTEST, FASTEST, or PEDESTRIAN. |
| avoid | No | List of road types to avoid: TOLLWAY, HIGHWAY, FERRY, UNPAVED. Israel only: IL_PA_A, IL_PA_B, IL_PA_C. |
| prefer | No | List of road types to prefer: TOLLWAY, HIGHWAY, FERRY, UNPAVED. Israel only: IL_PA_A, IL_PA_B, IL_PA_C. |
| simplification | No | Allows reducing the number of polyline points returned. At the furthest zoom levels, this can speed the rendering of the map with no loss of detail. At the closest zoom levels, more detail is often desired. Try matching simplification to zoom at first, then adjust the simplification level if needed until you get the best results. The furthest zoom level is 1; the most simplification is 1. The closest zoom level is 17; the least simplification is 17. |
Note the following behaviors of the Route parameters and of routes:
- Parameters can appear in any order for a given route.
- Actual line weight may change, depending on the DPI of the map.
GeoFencing and GeoMessaging Calls
This section covers the GeoFencing, GeoMessaging, and related calls supported by the Location Based Services.
Note: GeoFencing and GeoMessaging capabilities are supported for logged-in users only (user authorization). This means users have already approved sharing of their Intel® Identity Services user_id with the location-aware app.
A GeoFence is a virtual geographic boundary or area that is mapped onto an actual geographic location or area. Once a user creates a GeoFence, movement of a computing device in relation to that GeoFence can be used by the app to trigger events, such as displaying a GeoMessage.
A GeoMessage is a message available to recipients when client interpreted events occur that are associated with a GeoFence. For example, a user can establish a GeoFence around their favorite shopping mall, then define a GeoMessage that gets displayed to their friends whenever the user enters or leaves the mall. Or a user can leave messages for errands when a boundary is crossed to a location is visited.
Message publishers invite others to subscribe to their messages when they add potential recipients to a GeoMessage. Recipients can approve or block message subscriptions for privacy and change their subscription status at any time.
Notes:
- The Location Based Services provide the structures that apps can use to generate messages, but does not implement client or server-side events to trigger messages. Apps must implement any alerts or other events based on the current location and defined GepFences they created or subscribed to from other users.
Create GeoFence
Creates a GeoFence using the information in the call.
Once created, a GeoFence can be referenced by GeoMessaging calls. Apps can create up to 100 GeoFences per user using a bounding box or circle/radius.
URL Structure
https://api.intel.com:8081/location/v2/fences?access_token={access_token}
&name={name}&desc={desc}&shape_type={shape_type}
&lower_left_lat={lower_left_lat}&lower_left_lng={lower_left_lng}
&upper_right_lat={upper_right_lat}&upper_right_lng={upper_right_lng}
&lat={lat}&lng={lng}&radius={radius}&alt={alt}
(Alternate) Header: Bearer {access_token}
Method: POST
Parameters
| Parameters | Required? | Input Type | Description |
|---|---|---|---|
| access_token | Yes | URI or Request header | Unique access token to identify the session and as proof of prior authorization during the current session. |
| name | Yes | URI | A string that names the GeoFence. Examples: "My Sports Arena", "My Shopping Mall", "My Favorite Park", "L.A. Coliseum". Maximum length is 255 characters. |
| desc | No | URI | A string describing the GeoFence. Examples: "Things to pick up on way home", "Watching basketball", "At the mall". Maximum length is 255 characters. |
| shape_type | Yes | URI | The shape of the fence. Options are "BOUNDINGBOX" and "CIRCLE". |
| *Must include either lat/lng or a bounding box | |||
| lat | Yes* | URI | Center point latitude; used with lng and radius instead of a bounding box. |
| lng | Yes* | URI | Center point longitude; used with lat and radius instead of a bounding box. |
| radius | No | URI | Radius in meters; used with lng and lat instead of a bounding box. Default is 100,000 meters if radius is not specified. |
| lower_left_lat | Yes* | URI | Left lower corner latitude of a bounding box. |
| lower_left_lng | Yes* | URI | Left lower corner longitude of a bounding box. |
| upper_right_lat | Yes* | URI | Right upper corner latitude of a bounding box. |
| upper_right_lng | Yes* | URI | Right upper corner longitude of a bounding box. |
| alt | No | URI | This release of the Location Based Services supports JSON response only. |
Example Usage
Using Center and Radius
POST
https://api.intel.com:8081/location/v2/fences?access_token={access_token}
&name=My Favorite Shopping Mall&desc=Southcoast Plaza, Costa Mesa, CA
&shape_type=CIRCLE&lat=33.69103&lng=-117.88891&radius=500&alt=json
(Alternate) Header: Bearer {access_token}
Using Bounding Box
POST
https://api.intel.com:8081/location/v2/fences?access_token={access_token}
&name=My Favorite Shopping Mall&desc=Southcoast Plaza, Costa Mesa, CA
&shape_type=BOUNDINGBOX&lower_left_lat=33.68775&lower_left_lng=-117.891862
&upper_right_lat=33.694248&upper_right_lng=-117.885296&alt=json
(Alternate) Header: Bearer {access_token}
Response Codes
| HTTP Error/Code | Service Error Code | Message | Description |
|---|---|---|---|
| 201 | N/A | Operation successful. Fence was created successfully. | Fence was created successfully. Fence ID is contained in JSON response. Fence location is contained in HTTP header. Example: Location: https://api.intel.com:8081/location/v2/fences/1bfac4b6-59ec-11e2-bd3e-0aad11e55398 |
| 400 | LOC-2001 | Invalid input parameter <fieldname>. | Check the spelling, range, and/or context of the parameter <fieldname> and try again using a correct version. |
| 400 | LOC-2005 | Requested response format not supported <response>. | Only JSON is supported for this release of the Location Based Services. |
| 400 | LOC-2009 | Insufficient scope. | Scope {profile:basic} or {profile:full} have not granted for the access token. Can occur on creation of the first fence for a user if the scope is not correct. App can call Intel Identity Services (with scope=profile:basic or scope-profile:full) to request that the user grant access to the app. |
| 400 | LOC-2010 | Required field <xx> is missing. | Supply the required field and try again. |
| 401 | LOC-2101 | User login required for Enhanced API. | The call requires user authorization to ensure that the user has approved sharing of their information. (The user must log into their Intel® Identity account and approve sharing of their information with the application.) |
| 409 | LOC-2301 | Maximum fences for user reached. | This error is returned when the active fences owned by the user exceeds 100. |
JSON Response
{
"fenceId" : "1bfac4b6-59ec-11e2-bd3e-0aad11e55398"
}
Notes
- The GeoFencing, GeoMessaging, and Subscription calls are only supported for user authorization.
Get GeoFence
Retrieves the information for the specified GeoFence.
URL Structure
https://api.intel.com:8081/location/v2/fences/{fence_id}
?access_token={access_token}&include_messages={include_messages}
&include_recipients={include_recipients}&alt={alt}
(Alternate) Header: Bearer {access_token}
Method: GET
Parameters
| Parameters | Required? | Input Type | Description |
|---|---|---|---|
| access_token | Yes | URI or Request header | Unique access token to identify the session and as proof of prior authorization during the current session. |
| fence_id | Yes | URI | Unique value identifying a GeoFence that was previously created by the Create GeoFence call. |
| include_messages | No | URI | Boolean specifying whether or not the call should return the GeoMessages for the GeoFence(s). false = do not return the GeoMessages; true = return the GeoMessages. Default is false. |
| include_recipients | No | URI | Boolean specifying whether or not the call should return the recipients subscribed to the GeoMessages for the GeoFence(s). false = do not return the recipients for the GeoMessages; true = return the recipients for the GeoMessages. Default is false. Since recipents are defined on a per message basis, this parameter is ignored when include_messages = false. |
| alt | No | URI | This release of the Location Based Services supports JSON response only. |
Example Usage
GET
https://api.intel.com:8081/location/v2/fences/1bfac4b6-59ec-11e2-bd3e-0aad11e55398
?access_token={access_token}&include_messages=true&include_recipients=true&alt=json
(Alternate) Header: Bearer {access_token}
Response Codes
| HTTP Error/Code | Service Error Code | Message | Description |
|---|---|---|---|
| 200 | N/A | Operation successful. Fence returned. | The Get Fence call completed successfully and the requested fence was returned. |
| 400 | LOC-2001 | Invalid input parameter {fieldname}. | Check the spelling, range, and/or context of the parameter <fieldname> and try again using a correct version. |
| 400 | LOC-2005 | Requested response format not supported <response>. | Only JSON is supported for this release of the Location Based Services. |
| 401 | LOC-2101 | User login required for Enhanced API. | The call requires user authorization to ensure that the user has approved sharing of their information. (The user must log into their Intel® Identity account and approve sharing of their information with the application.) |
| 403 | LOC-2102 | User does not have permission for the operation. | Can occur when the user does not own the fence. Check the user id information and try again. |
| 404 | LOC-2302 | The fence is not found. | Can occur if the fence id is not correct or if the fence has already been deleted. Check the fence id and try again. |
JSON Response without Messages/Recipients
{
"data": {
"kind": "fence",
"items": [
{
"fenceId": "7e1d1ed0-5a15-11e2-bd3e-0aad11e55398",
"fenceName": "downtown area",
"fenceDescription": "circle fence for downtown",
"shapeType": "CIRCLE",
"createTime": "2013-01-09T04:31:53Z",
"modTime": "2013-01-09T04:31:53Z",
"active": true,
"centerLat": 52.1,
"centerLng": -0.17,
"radius": 7000
}
]
}
}
JSON Response with Messages and Recipients
{
"data": {
"kind": "fence",
"items": [
{
"fenceId": "7e1d1ed0-5a15-11e2-bd3e-0aad11e55398",
"fenceName": "downtown area",
"fenceDescription": "circle fence for downtown",
"shapeType": "CIRCLE",
"createTime": "2013-01-09T04:31:53Z",
"modTime": "2013-01-09T04:31:53Z",
"active": true,
"centerLat": 52.1,
"centerLng": -0.17,
"radius": 7000,
"messages": {
"kind": "message",
"items": [
{
"messageId": "872344e8-5a15-11e2-bd3e-0aad11e55398",
"fenceId": "7e1d1ed0-5a15-11e2-bd3e-0aad11e55398",
"title": "Maggie Shopping Alert!",
"content": "Shopping for the holidays now!",
"imageUrl": "http://www.bigzoomphotos.com/maggmalone/myimage.jpg",
"createTime": "2013-01-09T04:32:08Z",
"modTime": "2013-01-09T04:32:08Z",
"active": true,
"priority": "LOW",
"recipientList": "darcyp@atempisp.com",
"messageType": "SHOPPING",
"recipients": {
"kind": "recipient",
"items": [
{
"email": "darcyp@atempisp.com",
"fname": "darcy",
"lname": "peterson",
"subscribeTime": "2012-12-17T03:25:39Z"
}
]
}
}
]
}
}
]
}
}
Notes
- The GeoFencing, GeoMessaging, and Subscription calls are only supported for user authorization.
Get Multiple GeoFences
Retrieves all the GeoFences or all GeoFences of the specified type.
URL Structure
https://api.intel.com:8081/location/v2/fences/
?access_token={access_token}&include_messages={include_messages}
&include_recipients={include_recipients}&alt={alt}
(Alternate) Header: Bearer {access_token}
Method: GET
Parameters
| Parameters | Required? | Input Type | Description |
|---|---|---|---|
| access_token | Yes | URI or Request header | Unique access token to identify the session and as proof of prior authorization during the current session. |
| include_messages | No | URI | Boolean specifying whether or not the call should return the GeoMessages for the GeoFences. false = do not return the GeoMessages; true = return the GeoMessages. Default is false. |
| include_recipients | No | URI | Boolean specifying whether or not the call should return the recipients subscribed to the GeoMessages for the GeoFences. false = do not return the recipients for the GeoMessages; true = return the recipients for the GeoMessages. Default is false. Since recipents are defined on a per message basis, this parameter is ignored when include_messages = false. |
| alt | No | URI | This release of the Location Based Services supports JSON response only. |
Example Usage
GET
https://api.intel.com:8081/location/v2/fences/
?access_token={access_token}&include_messages=true
&include_recipients=true&alt=json
(Alternate) Header: Bearer {access_token}
Response Codes
| HTTP Error/Code | Service Error Code | Message | Description |
|---|---|---|---|
| 200 | N/A | Operation successful. Fence(s) returned. | The Get Multiple Fences call completed successfully and the requested fence(s) were returned. |
| 400 | LOC-2001 | Invalid input parameter {fieldname}. | Check the spelling, range, and/or context of the parameter <fieldname> and try again using a correct version. |
| 400 | LOC-2005 | Requested response format not supported <response>. | Only JSON is supported for this release of the Location Based Services. |
| 401 | LOC-2101 | User login required for Enhanced API. | The call requires user authorization to ensure that the user has approved sharing of their information. (The user must log into their Intel® Identity account and approve sharing of their information with the application.) |
JSON Response without Messages/Recipients
{
"data": {
"kind": "fence",
"items": [
{
"fenceId": "537a2f96-5a15-11e2-bd3e-0aad11e55398",
"fenceName": "office area",
"fenceDescription": "boundingbox fence for office area",
"shapeType": "BOUNDINGBOX",
"createTime": "2013-01-09T04:30:41Z",
"modTime": "2013-01-09T04:30:41Z",
"active": true,
"lowerLeftLat": 51.1,
"lowerLeftLng": -0.17,
"upperRightLat": 52.1,
"upperRightLng": -0.05
},
{
"fenceId": "7e1d1ed0-5a15-11e2-bd3e-0aad11e55398",
"fenceName": "downtown area",
"fenceDescription": "circle fence for downtown",
"shapeType": "CIRCLE",
"createTime": "2013-01-09T04:31:53Z",
"modTime": "2013-01-09T04:31:53Z",
"active": true,
"centerLat": 52.1,
"centerLng": -0.17,
"radius": 7000
}
]
}
}
JSON Response with Messages and Recipients
{
"data": {
"kind": "fence",
"items": [
{
"fenceId": "537a2f96-5a15-11e2-bd3e-0aad11e55398",
"fenceName": "office area",
"fenceDescription": "boundingbox fence for office area",
"shapeType": "BOUNDINGBOX",
"createTime": "2013-01-09T04:30:41Z",
"modTime": "2013-01-09T04:30:41Z",
"active": true,
"lowerLeftLat": 51.1,
"lowerLeftLng": -0.17,
"upperRightLat": 52.1,
"upperRightLng": -0.05,
"messages": {
"kind": "message",
"items": [
{
"messageId": "61da87a3-5a15-11e2-bd3e-0aad11e55398",
"fenceId": "537a2f96-5a15-11e2-bd3e-0aad11e55398",
"title": "Maggie Shopping Alert!",
"content": "Shopping for the holidays now!",
"imageUrl": "http://www.bigzoomphotos.com/maggmalone/myimage.jpg",
"createTime": "2013-01-09T04:31:05Z",
"modTime": "2013-01-09T04:31:05Z",
"active": true,
"priority": "LOW",
"recipientList": "sam43sampson456@hotmail.com;",
"messageType": "TRAVEL"
}
]
}
},
{
"fenceId": "7e1d1ed0-5a15-11e2-bd3e-0aad11e55398",
"fenceName": "downtown area",
"fenceDescription": "circle fence for downtown",
"shapeType": "CIRCLE",
"createTime": "2013-01-09T04:31:53Z",
"modTime": "2013-01-09T04:31:53Z",
"active": true,
"centerLat": 52.1,
"centerLng": -0.17,
"radius": 7000,
"messages": {
"kind": "message",
"items": [
{
"messageId": "872344e8-5a15-11e2-bd3e-0aad11e55398",
"fenceId": "7e1d1ed0-5a15-11e2-bd3e-0aad11e55398",
"title": "Maggie Shopping Alert!",
"content": "Shopping for the holidays now!",
"imageUrl": "http://www.bigzoomphotos.com/maggmalone/myimage.jpg",
"createTime": "2013-01-09T04:32:08Z",
"modTime": "2013-01-09T04:32:08Z",
"active": true,
"priority": "LOW",
"recipientList": "darcyp@atempisp.com",
"messageType": "SHOPPING",
"recipients": {
"kind": "recipient",
"items": [
{
"email": "darcyp@atempisp.com",
"fname": "darcy",
"lname": "peterson",
"subscribeTime": "2012-12-17T03:25:39Z"
}
]
}
}
]
}
}
]
}
}
Notes
- The GeoFencing, GeoMessaging, and Subscription calls are only supported for user authorization.
Delete GeoFence
Deletes the specified GeoFence.
URL Structure
https://api.intel.com:8081/location/v2/fences/{fence_id}
?access_token={access_token}&alt={alt}
(Alternate) Header: Bearer {access_token}
Method: DEL
Parameters
| Parameters | Required? | Input Type | Description |
|---|---|---|---|
| access_token | Yes | URI or Request header | Unique access token to identify the session and as proof of prior authorization during the current session. |
| fence_id | Yes | URI | Unique number identifying the fence to be deleted. This parameter is generated when a fence is created. |
| alt | No | URI | This release of the Location Based Services supports JSON response only. |
Example Usage
DEL
https://api.intel.com:8081/location/v2/fences/1bfac4b6-59ec-11e2-bd3e-0aad11e55398
?access_token={access_token}&alt=json
(Alternate) Header: Bearer {access_token}
Response Codes
| HTTP Error/Code | Service Error Code | Message | Description |
|---|---|---|---|
| 204 | N/A | (no content) | Fence was deleted successfully. |
| 400 | LOC-2005 | Requested response format not supported <response>. | Only JSON is supported for this release of the Location Based Services. |
| 401 | LOC-2101 | User login required for Enhanced API. | The call requires user authorization to ensure that the user has approved sharing of their information. (The user must log into their Intel® Identity account and approve sharing of their information with the application.) |
| 403 | LOC-2102 | User does not have permission for the operation. | Can occur when the user does not own the fence. Check the user id information and try again. |
| 404 | LOC-2302 | The fence is not found. | Can occur if the fence id is not correct or if the fence has already been deleted. Check the fence id and try again. |
JSON Response
(not applicable for this call)
Notes
- The GeoFencing, GeoMessaging, and Subscription calls are only supported for user authorization.
Create GeoMessage
Creates a GeoMessage for the specified GeoFence using the message information in the call.
GeoMessages are always associated with a GeoFence. Adding potential recipients to a GeoMessage results in invitations to those recipients to subscribe to the publisher's GeoMessages. (See Get Subscription and Update Subscription for recipient approval.) Even when recipients accept the subscription, the publisher must proactively include those same recipients on other GeoMessages for the recipient to receive those GeoMessages. It is possible to have more than one GeoMessage (with different recipient lists) associated with the same GeoFence.
URL Structure
https://api.intel.com:8081/location/v2/fences/{fence_id}/messages?access_token={access_token}
&title={title}&content={content}&recipients={recipients}
&image_url={image_url}&priority={priority}&message_type={message_type}&alt={alt}
(Alternate) Header: Bearer {access_token}
Method: POST
Parameters
| Parameters | Required? | Input Type | Description |
|---|---|---|---|
| access_token | Yes | URI or Request header | Unique access token to identify the session and as proof of prior authorization during the current session. |
| fence_id | Yes | URI | Unique number identifying the fence that the message is being associated with. |
| title | Yes | URI | A string specifying the title of the message. Example: "Maggie Alert!". Maximum length is 40 characters. |
| content | Yes | URI | A string specifying the content of the message. Example: "Shopping again!". Maximum length is 255 characters. |
| image_url | No | URI | A link to an image associated with the message. |
| priority | No | URI | Priority of the message. Available values: URGENT, NORMAL, LOW. |
| recipients | Yes | URI | A string containing a semi-colon delimited list of the email addresses of message recipients. |
| message_type | No | URI | Type of the message. Available values: GENERAL, TRAVEL, SHOPPING, FAMILY. |
| alt | No | URI | This release of the Location Based Services supports JSON response only. |
Example Usage
POST
https://api.intel.com:8081/location/v2/fences/1bfac4b6-59ec-11e2-bd3e-0aad11e55398/
messages?access_token={access_token}&title=Maggie Shopping Alert!
&content=Shopping for the holidays now!&priority=URGENT
&image_url=http://www.bigzoomphotos.com/maggmalone/myimage.jpg
&message_type=SHOPPING&recipients=darcyp@atempisp.com;tonimx12@atempisp.com&alt=json
(Alternate) Header: Bearer {access_token}
Response Codes
| HTTP Error/Code | Service Error Code | Message | Description |
|---|---|---|---|
| 201 | N/A | Operation successful. Message was created successfully. | Message was created successfully. Message ID is contained in JSON response. Message location is contained in HTTP header. Example: Location: https://api.intel.com:8081/location/v2/messages/c2dd5f10-5a18-11e2-bd3e-0aad11e55398. |
| 400 | LOC-2001 | Invalid input parameter <fieldname>. | Check the spelling, range, and/or context of the parameter <fieldname> and try again using a correct version. |
| 400 | LOC-2005 | Requested response format not supported <response>. | Only JSON is supported for this release of the Location Based Services. |
| 401 | LOC-2101 | User login required for Enhanced API. | The call requires user authorization to ensure that the user has approved sharing of their information. (The user must log into their Intel® Identity account and approve sharing of their information with the application.) |
| 403 | LOC-2102 | User does not have permission for the operation. | Can occur when the user does not own the fence. Check the user id information and try again. |
| 409 | LOC-2401 | Maximum messages for user reached. | This error is returned when the number of active messages owned by a user exceeds 1000. |
| 409 | LOC-2402 | Maximum messages for fence reached. | This error is returned when the number of active messages for a given fence exceeds 100. |
JSON Response
{
"messageId" : "c2dd5f10-5a18-11e2-bd3e-0aad11e55398"
}
Notes
- The GeoFencing, GeoMessaging, and Subscription calls are only supported for user authorization.
Get GeoMessage
Retrieves the GeoMessage associated with the message ID.
URL Structure
https://api.intel.com:8081/location/v2/messages/{message_id}
?access_token={access_token&alt={alt}
(Alternate) Header: Bearer {access_token}
Method: GET
Parameters
| Parameters | Required? | Input Type | Description |
|---|---|---|---|
| access_token | Yes | URI or Request header | Unique access token to identify the session and as proof of prior authorization during the current session. |
| message_id | Yes | URI | Unique number identifying the message being requested. |
| alt | No | URI | This release of the Location Based Services supports JSON response only. |
Example Usage
GET
https://api.intel.com:8081/location/v2/messages/{message_id}
?access_token={access_token}&alt=json
(Alternate) Header: Bearer {access_token}
Response Codes
| HTTP Error/Code | Service Error Code | Message | Description |
|---|---|---|---|
| 200 | N/A | Operation successful. Message/messages returned. | The Get Message call completed successfully and the requested message/messages were returned. |
| 400 | LOC-2005 | Requested response format not supported <response>. | Only JSON is supported for this release of the Location Based Services. |
| 401 | LOC-2101 | User login required for Enhanced API. | The call requires user authorization to ensure that the user has approved sharing of their information. (The user must log into their Intel® Identity account and approve sharing of their information with the application.) |
| 403 | LOC-2102 | User does not have permission for the operation. | Can occur when the user does not own the message or is not in the recipient list. Check the message id or recipient list information and try again. |
| 404 | LOC-2403 | The message is not found. | Can occur if the message id is not correct or if the message has already been deleted. Check the message id and try again. |
JSON Response
{
"data": {
"kind": "message",
"items": [
{
"messageId": "c2dd5f10-5a18-11e2-bd3e-0aad11e55398",
"fenceId": "7e1d1ed0-5a15-11e2-bd3e-0aad11e55398",
"title": "Maggie Shopping Alert!",
"content": "Shopping for the holidays now!",
"imageUrl": "http://www.bigzoomphotos.com/maggmalone/myimage.jpg",
"createTime": "2013-01-09T04:55:16Z",
"modTime": "2013-01-09T04:55:16Z",
"active": true,
"priority": "LOW",
"recipientList": "darcyp@atempisp.com;tonimx12@atempisp.com",
"messageType": "SHOPPING"
}
]
}
}
Notes
- The GeoFencing, GeoMessaging, and Subscription calls are only supported for user authorization.
Get Multiple GeoMessages
Retrieves all the GeoMessages for the user or the GeoMessages associated with the specified role/owner.
URL Structure
https://api.intel.com:8081/location/v2/messages/
?access_token={access_token}&role={role}&owner={owner}&alt={alt}
(Alternate) Header: Bearer {access_token}
&expiration_date={expiration_date}
Method: GET
Parameters
| Parameters | Required? | Input Type | Description |
|---|---|---|---|
| access_token | Yes | URI or Request header | Unique access token to identify the session and as proof of prior authorization during the current session. |
| role | No | URI | The messaging role associated with the desired message. Available roles are: OWNER, RECIPIENT, ALL. Default is ALL. |
| owner | No | URI | If provided, the response will only contain messages for this owner, when the role is either RECIPIENT or ALL. |
| alt | No | URI | This release of the Location Based Services supports JSON response only. |
Example Usage
GET
https://api.intel.com:8081/location/v2/messages?access_token={access_token}
&role=ALL&owner=magg34malone@atempisp.com&alt=json
(Alternate) Header: Bearer {access_token}
&expiration_date={expiration_date}
Response Codes
| HTTP Error/Code | Service Error Code | Message | Description |
|---|---|---|---|
| 200 | N/A | Operation successful. Message was returned. | The Get Message call completed successfully and the requested message/messages were returned. |
| 400 | LOC-2001 | Invalid input parameter <fieldname>. | Check the spelling, range, and/or context of the parameter <fieldname> and try again using a correct version. |
| 400 | LOC-2005 | Requested response format not supported <response>. | Only JSON is supported for this release of the Location Based Services. |
| 401 | LOC-2101 | User login required for Enhanced API. | The call requires user authorization to ensure that the user has approved sharing of their information. (The user must log into their Intel® Identity account and approve sharing of their information with the application.) |
JSON Response
{
"data": {
"kind": "message",
"items": [
{
"messageId": "c2dd5f10-5a18-11e2-bd3e-0aad11e55398",
"fenceId": "7e1d1ed0-5a15-11e2-bd3e-0aad11e55398",
"title": "Maggie Shopping Alert!",
"content": "Shopping for the holidays now!",
"imageUrl": "http://www.bigzoomphotos.com/maggmalone/myimage.jpg",
"createTime": "2013-01-09T04:55:16Z",
"modTime": "2013-01-09T04:55:16Z",
"active": true,
"priority": "LOW",
"recipientList": "darcyp@atempisp.com;tonimx12@atempisp.com",
"messageType": "SHOPPING"
}
]
}
}
Notes
- The GeoFencing, GeoMessaging, and Subscription calls are only supported for user authorization.
Update GeoMessage
Updates the specified GeoMessage using the message information in the call.
Adding potential recipients to a GeoMessage results in invitations to those recipients to subscribe to the publisher's GeoMessages. (See Get Subscription and Update Subscription for recipient approval.) Even when recipients accept the subscription, the publisher must proactively include those same recipients on subsequent GeoMessages for the recipient to receive those subsequent GeoMessages.
URL Structure
Updating a GeoMessage associated with a GeoFence
https://api.intel.com:8081/location/v2/fences/{fence_id}/messages/{message_id}
?access_token={access_token}&title={title}&content={content}
&recipients={recipients}&image_url={image_url}
&priority={priority}&message_type{message_type}&active={active}
&do_not_show={do_not_show}&alt={alt}
(Alternate) Header: Bearer {access_token}
Method: PUT
Updating a GeoMessage not associated with a GeoFence
https://api.intel.com:8081/location/v2/messages/{message_id}?access_token={access_token}
&title={title}&content={content}&recipients={recipients}
&image_url={image_url}&priority={priority}
&message_type{message_type}&active={active}
&do_not_show={do_not_show}&alt={alt}
(Alternate) Header: Bearer {access_token}
Method: PUT
Parameters
| Parameters | Required? | Input Type | Description |
|---|---|---|---|
| access_token | Yes | URI or Request header | Unique access token to identify the session and as proof of prior authorization during the current session. |
| message_id | Yes | URI | Unique number identifying the message being updated. |
| fence_id | No | URI | Unique number identifying the fence that message is associated with. Only required when associating a message with a different fence than the current fence. |
| title | No | URI | A string specifying the title of the message. Example: "Maggie Alert!". Maximum length is 255 characters. |
| content | No | URI | A string specifying the content of the message. Example: "Shopping again!". Maximum length is 255 characters. |
| recipients | No | URI | A string containing a semi-colon delimited list of the email addresses of message recipients. |
| image_url | No | URI | A link to an image associated with the message. |
| priority | No | URI | Priority of the message. Available values: URGENT, NORMAL, LOW. |
| message_type | No | URI | Type of the message. Available values: GENERAL, TRAVEL, SHOPPING, FAMILY. |
| active | No | URI | Boolean to activate (true) or inactivate (false) a message. |
| do_not_show | No | URI | Boolean to show (=true) or not show (=false) the message if the user is in the recipient list. If this parameter is present, it supercedes all other optional parameters. |
| alt | No | URI | This release of the Location Based Services supports JSON response only. |
Example Usage
Set an inactive message to "active"
PUT
https://api.intel.com:8081/location/v2/fences/{fence_id}/
messages/{message_id}?access_token={access_token}
&active=true&alt=json
(Alternate) Header: Bearer {access_token}
Set message to "do not show"
PUT
https://api.intel.com:8081/location/v2/messages/{message_id}
?access_token={access_token}&do_not_show=true&alt=json
(Alternate) Header: Bearer {access_token}
Response Codes
| HTTP Error/Code | Service Error Code | Message | Description |
|---|---|---|---|
| 201 | N/A | Operation successful. Message was updated successfully. | Message was updated successfully. Message ID is contained in JSON response. Message location is contained in HTTP header. Example: Location: https://api.intel.com:8081/location/v2/messages/c2dd5f10-5a18-11e2-bd3e-0aad11e55398. |
| 204 | N/A | Operating successful. Message was marked ad hidden or unhidden. | Message was marked as hidden or unhidden based on the value of do_not_show. |
| 400 | LOC-2001 | Invalid input parameter <fieldname>. | Check the spelling, range, and/or context of the parameter <fieldname> and try again using a correct version. |
| 400 | LOC-2005 | Requested response format not supported <response>. | Only JSON is supported for this release of the Location Based Services. |
| 401 | LOC-2101 | User login required for Enhanced API. | The call requires user authorization to ensure that the user has approved sharing of their information. (The user must log into their Intel® Identity account and approve sharing of their information with the application.) |
| 403 | LOC-2102 | User does not have permission for the operation. | Can occur when the user does not own the message (or the fence when fence_id is present). Can also occur if user is not in the message recipient list when using do_not_show. Check the information and try again. |
| 404 | LOC-2302 | The fence is not found. | Can occur if the fence id is not correct or if the fence has already been deleted. Check the fence id and try again. |
| 404 | LOC-2403 | The message is not found. | Can occur if the message id is not correct or if the message has already been deleted. Check the message id and try again. |
| 409 | LOC-2402 | Maximum messages for fence reached. | This error is returned when the active messages for a given fence exceeds 100. |
JSON Response
{
"data": {
"messageId": "c2dd5f10-5a18-11e2-bd3e-0aad11e55398",
"fenceId": "537a2f96-5a15-11e2-bd3e-0aad11e5539",
"title": "Maggie Shopping Alert!",
"content": "Shopping for the holidays now!",
"imageUrl": "http://www.bigzoomphotos.com/maggmalone/myimage.jpg",
"createTime": "2012-12-10T13:01:36Z",
"modTime": "2012-12-10T16:11:05Z",
"active": true,
"priority": "NORMAL",
"recipientList": "darcyp@atempisp.com;tonimx12@atempisp.com;",
"messageType": "GENERAL"
}
}
Notes
- The GeoFencing, GeoMessaging, and Subscription calls are only supported for user authorization.
Delete GeoMessage
Deletes the specified GeoMessage.
URL Structure
https://api.intel.com:8081/location/v2/messages/{message_id}
?access_token={access_token}&alt={alt}
(Alternate) Header: Bearer {access_token}
Method: DEL
Parameters
| Parameters | Required? | Input Type | Description |
|---|---|---|---|
| access_token | Yes | URI or Request header | Unique access token to identify the session and as proof of prior authorization during the current session. |
| message_id | Yes | URI | Unique number identifying the message to be deleted. This parameter is generated when a message is created. |
| alt | No | URI | This release of the Location Based Services supports JSON response only. |
Example Usage
DEL
https://api.intel.com:8081/location/v2/messages/{message_id}
?access_token={access_token}&alt=json
(Alternate) Header: Bearer {access_token}
Response Codes
| HTTP Error/Code | Service Error Code | Message | Description |
|---|---|---|---|
| 204 | N/A | (no content) | Message was deleted successfully. |
| 400 | LOC-2005 | Requested response format not supported <response>. | Only JSON is supported for this release of the Location Based Services. |
| 401 | LOC-2101 | User login required for Enhanced API. | The call requires user authorization to ensure that the user has approved sharing of their information. (The user must log into their Intel® Identity account and approve sharing of their information with the application.) |
| 403 | LOC-2102 | User does not have permission for the operation. | Can occur when the user does not own the message. Check the user id information and try again. |
| 404 | LOC-2403 | The message is not found. | Can occur if the message id is not correct or if the message has already been deleted. Check the message id and try again. |
JSON Response
(not applicable for this call)
Notes
- The GeoFencing, GeoMessaging, and Subscription calls are only supported for user authorization.
Get Subscription
Retrieves subscriptions for the user based on specified status.
The app uses this call to regularly poll the Location Based Services for new and existing subscriptions. The call can poll for all subscriptions or only those of a specified status.
URL Structure
https://api.intel.com:8081/location/v2/subscriptions?access_token={access_token}
&status={status}&alt={alt}
(Alternate) Header: Bearer {access_token}
Method: GET
Parameters
| Parameters | Required? | Input Type | Description |
|---|---|---|---|
| access_token | Yes | URI or Request header | Unique access token to identify the session and as proof of prior authorization during the current session. |
| status | No | URI | Status of the subscription(s) to be returned. Available values: PENDING, ACCEPTED, REJECTED, ALL. Default is ALL. |
| alt | No | URI | This release of the Location Based Services supports JSON response only. |
Example Usage
GET
https://api.intel.com:8081/location/v2/subscriptions?access_token={access_token}
&status=PENDING&alt=json
(Alternate) Header: Bearer {access_token}
Response Codes
| HTTP Error/Code | Service Error Code | Message | Description |
|---|---|---|---|
| 200 | N/A | Operation successful. Subscription/subscriptions returned. | The Get Subscription call completed successfully and the requested subscription/subscriptions were returned. |
| 400 | LOC-2001 | Invalid input parameter <fieldname>. | Check the spelling, range, and/or context of the parameter <fieldname> and try again using a correct version. |
| 400 | LOC-2005 | Requested response format not supported <response>. | Only JSON is supported for this release of the Location Based Services. |
| 401 | LOC-2101 | User login required for Enhanced API. | The call requires user authorization to ensure that the user has approved sharing of their information. (The user must log into their Intel® Identity account and approve sharing of their information with the application.) |
JSON Response
{
"data":{
"kind": "subscription",
"items": [
{
"subscriptionId": "760abbb5-5a3a-11e2-bd3e-0aad11e55398",
"subscriptionType": "MESSAGE",
"fname": "darcy",
"lname": "peterson",
"email": "darcyp@atempisp.com",
"subscriptionStatus": “ACCEPTED”,
"createTime": "2012-12-10T13:01:36Z",
"actionTime": "2012-12-10T13:01:36Z"
},
{
"subscriptionId": "7e1d1ed0-5a15-11e2-bd3e-0aad11e55398",
"subscriptionType": "MESSAGE",
"fname": "toni",
"lname": "mx",
"email": "tonimx12@atempisp.com",
"subscriptionStatus": “PENDING”,
"createTime": "2012-12-10T13:01:36Z",
"actionTime": null
}
]
}
}
Notes
- The GeoFencing, GeoMessaging, and Subscription calls are only supported for user authorization.
Update Subscription
Accepts/declines a subscription relationship for the user.
Subscription requests originate from the publisher and are approved or blocked by the recipient. A subscription relationship is established on the first subscription acceptance and persists until blocked. Once a subscription relationship is established, the recipient will continue to receive GeoMessages from that publisher, as long as the publisher includes that recipient in the GeoMessages that the publisher creates/updates.
URL Structure
https://api.intel.com:8081/location/v2/subscriptions/{subscription_id}
?access_token={access_token}&status={updated_status}&alt={alt}
(Alternate) Header: Bearer {access_token}
Method: PUT
Parameters
| Parameters | Required? | Input Type | Description |
|---|---|---|---|
| access_token | Yes | URI or Request header | Unique access token to identify the session and as proof of prior authorization during the current session. |
| subscription_id | Yes | URI | The unique number identifying the subscription to be updated. |
| status | Yes | URI | Identifies the status being assigned to the subscription. Available values: REJECTED, ACCEPTED. |
| alt | No | URI | This release of the Location Based Services supports JSON response only. |
Example Usage
PUT
https://api.intel.com:8081/location/v2/subscriptions/{subscription_id}
?access_token={access_token}&updated_status=ACCEPTED&alt=json
(Alternate) Header: Bearer {access_token}
Response Codes
| HTTP Error/Code | Service Error Code | Message | Description |
|---|---|---|---|
| 200 | N/A | Operation successful. Subscription was updated successfully. | Subscription was updated successfully. |
| 400 | LOC-2001 | Invalid input parameter <fieldname>. | Check the spelling, range, and/or context of the parameter <fieldname> and try again using a correct version. |
| 400 | LOC-2005 | Requested response format not supported <response>. | Only JSON is supported for this release of the Location Based Services. |
| 401 | LOC-2101 | User login required for Enhanced API. | The call requires user authorization to ensure that the user has approved sharing of their information. (The user must log into their Intel® Identity account and approve sharing of their information with the application.) |
| 403 | LOC-2102 | User does not have permission for the operation. | Can occur when the user does not own the subscription. Check the user id information and try again. |
| 404 | LOC-2600 | The subscription is not found. | Can occur if the subscription id is not correct or if the subscription has already been deleted. Check the subscription id and try again. |
JSON Response
{
"data": {
"subscriptionId": "760abbb5-5a3a-11e2-bd3e-0aad11e55398",
"subscriptionType": "MESSAGE",
"fname": "darcy",
"lname": "peterson",
"email": "darcyp@atempisp.com",
"subscriptionStatus": "ACCEPTED",
"createTime": "2012-12-10T13:01:36Z",
"actionTime": "2012-12-11T15:11:03Z"
}
}
Notes
- The GeoFencing, GeoMessaging, and Subscription calls are only supported for user authorization.
- Subscription requests persist, even after being REJECTED. This allows a subscription to be turned off at one point in time and turned back on later.
Error Handling
When errors are detected during an API call, an HTTP error is returned with detailed error information in the body of the JSON response. The following example shows one possible error message for HTTP Error 400:
{
"error": {
"code": "LOC-2001",
"requestid": "E2E2507a-da13-4b80-803e-32c7b7d6dd5b",
"message": "Invalid input parameter countryCode"
}
}
Each call may generate a different set of possible HTTP errors and error codes. The following table lists the HTTP errors that can be returned by the Location Based Services. A subset of errors can be returned for the different calls. Note that HTTP code 200 indicates a successful communication with the Location Based Services, not a successful call. The app must check the body of the response for error information results.
HTTP Response Codes
| HTTP Code | Summary | Description |
|---|---|---|
| 200 | OK | Communication was successful. Note: Check body for results as error information may still be present even though the communication succeeded. |
| 201 | OK | Successfully created. |
| 204 | OK | Successfully deleted. |
| 400 | Bad Request | A provided parameter was not valid or a required parameter was missing. This can include the case where the access token was missing. |
| 401 | Unauthorized | The access token provided was not valid. |
| 403 | Forbidden | The requested information cannot be viewed by the acting user. |
| 404 | Not Found | The resource does not exist. Verify that the URL is correct. |
| 405 | Method Not Allowed | The request attempted to use any other method than GET. |
| 409 | Conflict | The request could not be successfully completed due to a conflict between the requested state and the limits or the current state of the resource. |
| 500 | Internal Server Error | Servers are not working as expected. Retry the request later. |
Error Codes
The following table lists the detailed error codes that may appear in the body of responses in addition to the HTTP codes. A subset of errors can be returned for the different calls.
Location Based Services Error Codes
| Service Error Code | Message | Description |
|---|---|---|
| LOC-2000 | General Error. | A general error was encountered, but there is not enough information to further specify the cause of the error. |
| LOC-2001 | Invalid input parameter {fieldname}. | Check the spelling, range, and/or context of the parameter <fieldname> and try again using a correct version. |
| LOC-2002 | API not authorized. | Restart the Location Based Services session, making sure the proper "scope" is requested during authorization. |
| LOC-2003 | API not available. | May occur if supporting service cannot be contacted. Retry the call later. |
| LOC-2005 | Requested response format not supported <response>. | Only JSON is supported for this release of the Location Based Services. |
| LOC-2007 | The houseNumber length in the request exceeds 10. | The house_number supports a maximum number of 10 digits. |
| LOC-2008 | Country code not supported. | The country code is not a valid one. Recheck the country code and retry. |
| LOC-2009 | Insufficient scope. | Scope {profile:basic} has not granted for the access token. Can occur on creation of the first fence for a user if the scope is not correct. App can call Intel Identity Services (with scope=profile:basic) to request that the user grant access to the app. |
| LOC-2010 | Required field {xx} is missing. | Supply the required field and try again. |
| LOC-2011 | Media type not supported. | Unsupported Content-Type in the header. The only supported media type is JSON. |
| LOC-2014 | Coordinates are valid by address is out of range. | The address does not match the known addresses for the search. Recheck the address and retry. |
| LOC-2100 | POI category is out of range. | The geographic area used for the search is out of range for the type of data requested. Example: Searching for gas stations in the middle of an ocean where no islands exist. |
| LOC-2101 | User login required for Enhanced API. | The call requires user authorization to ensure that the user has approved sharing of their information. (The user must log into their Intel® Identity account and approve sharing of their information with the application.) |
| LOC-2102 | User does not have permission for the operation. | Can occur when the user does not own the resource. Check the user id information and try again. |
| LOC-2200 | No navigable route found. | The services was unable to determine a route. Try the call again with a simpler route. |
| LOC-2201 | Too many polyline points in pedestrian route. | The pedestrian route would require too many polyline points. Try the call again with a simpler route or at a lower zoom level (zoomed out). |
| LOC-2202 | Bad via location provided for route search. | viaPoint specifies a bad location, such as a stopping point in a body of water. |
| LOC-2203 | Bad origin or destination coordinates. | There is likely something wrong with the coordinates. Check the validity of the coordinates and retry the call. |
| LOC-2204 | Route cannot be generated, identical addresses. | The origin and destination coordinates are the same. Alter at least one coordinate and retry the call. |
| LOC-2301 | Maximum fences for user reached. | This error is returned when the active fences owned by the user exceeds 100. |
| LOC-2302 | The fence is not found. | Can occur if the fence id is not correct or if the fence has already been deleted. Check the fence id and try again. |
| LOC-2401 | Maximum messages for user reached. | This error is returned when the active messages owned by the user exceeds 1000. |
| LOC-2402 | Maximum messages for fence reached. | This error is returned when the active messages for a given fence exceeds 100. |
| LOC-2403 | The message is not found. | Can occur if the message id is not correct or if the message has already been deleted. Check the message id and try again. |
| LOC-2600 | The subscription is not found. | Can occur if the subscription id is not correct or if the subscription has already been deleted. Check the subscription id and try again. |
| LOC-4000 | Error executing call to DB: {id} | Internal Location Based Services database error. |
Reference Tables
Country/Map Support List
The following table lists map availability by country.
| Country | Map Supported? |
|---|---|
| Afghanistan | No |
| Albania | Yes |
| Algeria | No |
| American Samoa | No |
| Andorra | Yes |
| Angola | No |
| Anguilla | No |
| Antigua and Barbuda | No |
| Argentina | Yes |
| Armenia | No |
| Australia | Yes |
| Austria | Yes |
| Azerbaijan | No |
| Bahamas | No |
| Bahrain | Yes |
| Bangladesh | No |
| Barbados | No |
| Belarus | Yes |
| Belgium | Yes |
| Belize | No |
| Benin | No |
| Bermuda | No |
| Bhutan | No |
| Bolivia | No |
| Bosnia-Herzegovina | Yes |
| Botswana | Yes |
| Brazil | Yes |
| British Indian Ocean Territory | No |
| British Virgin Islands | No |
| Brunei Darussalam | Yes |
| Bulgaria | Yes |
| Cambodia | No |
| Cameroon | No |
| Canada | Yes |
| Cape Verde | No |
| Cayman Islands | No |
| Central African Republic | No |
| Chad | No |
| Chile | No |
| China | No |
| Christmas Island | No |
| Clipperton Island | No |
| Cocos (Keeling) Islands | No |
| Colombia | No |
| Comoros | No |
| Congo, Democratic Republic of the | No |
| Congo | No |
| Cook Islands | No |
| Costa Rica | No |
| Cote d'Ivoire | No |
| Croatia | Yes |
| Cuba | No |
| Cyprus | No |
| Czech Republic | Yes |
| Denmark | Yes |
| Djibouti | No |
| Dominica | No |
| Dominican Republic | No |
| Ecuador | No |
| Egypt | No |
| El Salvador | No |
| Equatorial Guinea | No |
| Eritrea | No |
| Estonia | Yes |
| Ethiopia | No |
| Falkland Islands (Malvinas) | No |
| Faeroe Islands | No |
| Fiji | No |
| Finland | Yes |
| France | Yes |
| French Guiana | No |
| French Polynesia | No |
| French Southern & Antarctic Lands | No |
| Gabon | No |
| Gambia | No |
| Georgia | No |
| Germany | Yes |
| Gibraltar | Yes |
| Ghana | No |
| Greece | Yes |
| Greenland | No |
| Grenada | No |
| Grenadines | No |
| Guadeloupe | No |
| Guam | No |
| Guatemala | No |
| Guinea | No |
| Guinea-Bissau | No |
| Guyana | No |
| Haiti | No |
| Heard and MacDonald Islands | No |
| Honduras | No |
| Hong Kong | Yes |
| Hungary | Yes |
| Iceland | No |
| India | Yes |
| Indonesia | Yes |
| Iran | No |
| Iraq | No |
| Ireland | Yes |
| Israel | Yes |
| Italy | Yes |
| Jamaica | No |
| Japan | No |
| Jordan | No |
| Kazakhstan | No |
| Kenya | No |
| Kiribati | No |
| Korea, Democratic People's | No |
| Korea, Republic of (South) | No |
| Kuwait | Yes |
| Kyrgyzstan | No |
| Laos | No |
| Latvia | Yes |
| Lebanon | No |
| Lesotho | Yes |
| Liberia | No |
| Libya | No |
| Liechtenstein | Yes |
| Lithuania | Yes |
| Luxembourg | Yes |
| Macao | No |
| Macedonia | Yes |
| Madagascar | No |
| Malawi | No |
| Malaysia | Yes |
| Maldives | No |
| Mali | No |
| Malta | No |
| Marshall Islands | No |
| Mauritania | No |
| Mauritius | No |
| Mayotte | No |
| Mexico | Yes |
| Micronesia | No |
| Moldova | Yes |
| Monaco | Yes |
| Mongolia | No |
| Montenegro | Yes |
| Montserrat | No |
| Morocco | No |
| Mozambique | No |
| Myanmar | No |
| Namibia | Yes |
| Nauru | No |
| Nepal | No |
| Netherlands | Yes |
| Netherlands Antilles | No |
| New Caledonia | No |
| New Zealand | Yes |
| Nicaragua | No |
| Niger | No |
| Nigeria | No |
| Niue | No |
| Norfolk Island | No |
| Northern Mariana Islands | No |
| Norway | Yes |
| Oman | Yes |
| Pakistan | No |
| Palau | No |
| Panama | No |
| Papua New Guinea | No |
| Paraguay | No |
| Peru | No |
| Philippines | No |
| Poland | Yes |
| Portugal | Yes |
| Qatar | Yes |
| Romania | Yes |
| Russian Federation | Yes |
| Rwanda | No |
| Saint Kitts and Nevis | No |
| Saint Lucia | No |
| Saint Pierre and Miquelon | No |
| Saint Vincent | No |
| Saint-Helena | No |
| Samoa | No |
| San Marino | Yes |
| Sao Tome and Principe | No |
| Saudi Arabia | Yes |
| Senegal | No |
| Serbia | Yes |
| Seychelles | No |
| Sierra Leone | No |
| Singapore | Yes |
| Slovakia | Yes |
| Slovenia | Yes |
| Solomon Islands | No |
| Somalia | No |
| South Africa | Yes |
| Spain | Yes |
| Sri Lanka | No |
| Sudan | No |
| Suriname | No |
| Swaziland | Yes |
| Sweden | Yes |
| Switzerland | Yes |
| Syria | No |
| Taiwan | Yes |
| Tajikistan | No |
| Tanzania | No |
| Thailand | Yes |
| Timor-Leste | No |
| Togo | No |
| Tokelau | No |
| Tonga | No |
| Trinidad and Tobago | No |
| Tunisia | No |
| Turkey | Yes |
| Turkmenistan | No |
| Turks and Caicos Islands | No |
| Tuvalu | No |
| Uganda | No |
| Ukraine | Yes |
| United Arab Emirates | Yes |
| United Kingdom | Yes |
| United States | Yes |
| Uruguay | No |
| Uzbekistan | No |
| Vanuatu | No |
| Vatican City | Yes |
| Venezuela | No |
| Vietnam | No |
| Wallis and Futuna Islands | No |
| Yemen | No |
| Zambia | No |
| Zimbabwe | No |