GetPOIs Request
This call is used to request the points of interest to be displayed for a particular layer.
URI:
http://<poiUrl>?<parameters>
Request example:
http://devAPI.example.com/getPOIs/?countryCode=IN&lon=4.887339 &userId=ed48067cda8e1b985dbb8ff3653a2da4fd490a37 &radius=6245&lat=52.377544&layerName=snowy4&accuracy=100
HTTP request header:
User-Agent: The user agent originally set by the client. Format is: Layar/x.y [OS name]/x.y.z ([Brand] [Model]), for example "Layar/3.1 Android/2.1 (Motorola Milestone)" , "Layar/3.1 iPhoneOS/3.1.2 (Apple iPhone3GS)" or "Layar/3.0 BadaOS/3.0.4(Samsung Wave)".
poiUrl:
The API endpoint URL of the POI service provider. This can be defined in the publishing site.
Request Parameters:
The detailed explanation of each parameter is listed below.
- Note that new request parameters may be added in future versions of Layar. Therefore the layer developer should always ignore unknown params rather than throwing an error.
- If you need to ensure the request is genuine, request OAuth signing and check it. This way only genuine requests from the Layar server can be filtered.
- Please make sure that you are not using reserved parameters from Layar in your own API endPoint URL. After Layar API v4.0, all new reserved parameters introduced will have "ly_" prepended to them, in order to avoid conflicts with parameters used in layers. custom parameters therefore should not start with "ly_".
| userId |
string |
A unique id of the user. |
| Mandatory/Optional: |
mandatory |
| Introduced API: |
introduced in v2.1; modified in v6.2 for privacy reasons. |
| Detailed Description: |
A unique ID of the end-user, anonymized. It is a hashed code. This ID is created when the layar app is installed the first time. It will be kept when the app is updated. A new ID is generated when the app is completely removed from the device and replaced with a new download.
NOTE: Since the algorithm of generating this unique ID is changed in API v6.2, the userID will be replaced when upgrading to v6.2. In future releases, as long as the Layar app is not removed completely, the userID will be kept. |
| Example: |
userId=42241049345 |
| layerName |
string |
The identifier of the layer. |
| Mandatory/Optional: |
mandatory |
| Introduced API: |
v2.1 |
| Detailed Description: |
The layer name defined in the publishing site. This is a unique name used to identify a layer. |
| Example: |
layerName=hyves |
| version |
string |
The version of the API used by the client. |
| Mandatory/Optional: |
mandatory |
| Introduced API: |
v2.1 |
| Detailed Description: |
This indicates the version of the API that the phone is using. Note that for older version, strings like "ip3.0" might be used. However, this version string cannot be used anymore to differentiate clients (Android and iPhone clients use the same version string, as it's the API version). Current list of versions: "2.1", "2.2", "3.0" "3.1", "3.5", ”4.0", "5.0" and "6.0". Developers can use this parameter to decide which JSON response should be returned so that the same layer can work on various clients with optimized performance. |
| Example: |
version=6.0 |
| lat |
decimal |
The latitude of current position of the user. (GPS coordinate) |
| Mandatory/Optional: |
mandatory |
| Introduced API: |
v2.1 |
| Example: |
lat=52.360112 |
| lon |
decimal |
The longitude of current position of the user. (GPS coordinate) |
| Mandatory/Optional: |
mandatory |
| Introduced API: |
v2.1 |
| Example: |
lon=-4.895665 |
| countryCode |
string |
The home country of the user. |
| Mandatory/Optional: |
mandatory |
| Introduced API: |
v2.1 |
| Detailed Description: |
This is the home country of the user, as determined by the network provider of the SIM card in the phone. If this is not available (e.g. iPhone or no SIM card inserted), it will return the locale value set on the phone. NOTE: If you have development mode on, the country setting in developer settings will overrule the values from SIM card and Locale setting. List of country code can be found here. |
| Example: |
countryCode=NL |
| lang |
string |
The language used on the layar client. |
| Mandatory/Optional: |
mandatory |
| Introduced API: |
v3.0 |
| Detailed Description: |
This is the language setting found under locale setting on the phone. Currently it is using ISO 639-1 |
| Example: |
lang=EN |
| action |
string |
Specifies whether the layar client is requesting a full refresh or an update. |
| Mandatory/Optional: |
mandatory |
| Introduced API: |
v4.0 |
| Detailed Description: |
This tells the poi provider whether the client is requesting a full refresh of the layer or just an update: This can be caused by the refresh parameter(fullRefresh) in the getPOIs response or by an intent containing the "action=update" command. Default action=refresh |
| Example: |
action=update |
| accuracy |
integer |
The accuracy of the current location. |
| Mandatory/Optional: |
optional |
| Introduced API: |
v2.1 |
| Detailed Description: |
the accuracy of the current location, as given by the device. Note that accuracy may not be given if a fixed location is used (developer feature). |
| Example: |
accuracy=50 |
| pageKey |
string |
The key of the next page. |
| Mandatory/Optional: |
optional |
| Detailed Description: |
If the POIs are spread over more pages, the Layar Server can request the next page using this pageKey (if received in the previous getPOIs response) |
| Example: |
pageKey=aldsfj9348dk |
The following parameters are used for oAuth signing. If oAuth signing is enabled on the publishing site, all these parameters are mandatory.
| oauth_consumer_key |
string |
The oauth consumer key defined in the publishing site. |
| Mandatory/Optional: |
optional |
| Introduced API: |
v2.1 |
| Example: |
oauth_consumer_key=f43f3p214k3103 |
| oauth_signature_method |
string |
this will always be HMAC-SHA1 |
| Mandatory/Optional: |
optional |
| Introduced API: |
v2.1 |
| Example: |
oauth_signature_method=HMAC-SHA1 |
| oauth_timestamp |
integer |
timestamp for the request. |
| Mandatory/Optional: |
optional |
| Introduced API: |
v2.1 |
| Example: |
oauth_timestamp=1191242096 |
| oauth_nonce |
string |
unique nonce to rule out replay attacks |
| Mandatory/Optional: |
optional |
| Introduced API: |
v2.1 |
| Example: |
oauth_nonce=kllo9940pd9333jh |
| oauth_version |
string |
oauth version used. This wiill always be 1.0 |
| Mandatory/Optional: |
optional |
| Introduced API: |
v2.1 |
| Example: |
oauth_version=1.0 |
| oauth_signature |
string |
HMAC-SHA1 signature using the Signature Base String as text and the Consumer Secret (no token secret) as key. The consumer secret is submitted by the developer on the Layar Publishing Website. |
| Mandatory/Optional: |
optional |
| Introduced API: |
v2.1 |
| Example: |
oauth_signature=tR3+Ty81lMeYar/Fid0kMTYa/WM= |
| oauth_body_hash |
string |
The request body hash value. Please read here for more information. |
| Mandatory/Optional: |
optional |
| Introduced API: |
v2.1 |
| Example: |
oauth_body_hash=2jmj7l5rSw0yVb%2FvlWAYkK%2FYBwk%3D |
| RADIOLIST |
string |
The option id corresponding to the value of the radio button list option selected by the user on the client. |
| Mandatory/Optional: |
optional |
| Introduced API: |
v2.1 |
| Example: |
RADIOLIST=1001 |
| SEARCHBOX, SEARCHBOX_n |
string |
the search term entered by the user. When multiple search boxes are defined (up to 3), they will be numbered _2, _3. |
| Mandatory/Optional: |
optional |
| Introduced API: |
v2.1 for SEARCHBOX; v3.0 for SEARCHBOX_2 and SEARCHBOX_3. |
| Example: |
SEARCHBOX=bar, SEARCHBOX_3=foo |
| CUSTOM_SLIDER, CUSTOM_SLIDER_n |
float/integer |
The value for the custom slider selected b the user. When multiple sliders are defined (up to 3), they will be numbered _2, _3. |
| Mandatory/Optional: |
optional |
| Introduced API: |
v2.1 for CUSTOM_SLIDER; v3.0 for CUSTOM_SLIDER_2 and CUSTOM_SLIDER_3. |
| Example: |
CUSTOM_SLIDER=45.6, CUSTOM_SLIDER_2=20 |
| radius |
integer |
The value for the search radius selected by the user in the RANGE_SLIDER (unit in meters). |
| Mandatory/Optional: |
mandatory before v3.0; Since v3.0, it is optional. |
| Introduced API: |
v2.1 |
| Detailed Description: |
From v3 on, radius is not mandatory anymore and flexible radius can be used (if the default value of the range slider is empty).
NOTE: If you are using flexible radius, you need to return a radius value in the JSON response. Please check GetPOIs Response page for more information. |
| Example: |
radius=2500 |
| CHECKBOXLIST |
string |
The value(s) selected for the checkbox: multiple values get passed using comma-separated values. |
| Mandatory/Optional: |
optional |
| Introduced API: |
v3.0 |
| Example: |
CHECKBOXLIST=4,7 |
| localCountryCode |
string |
country code for the current country the device is located in. |
| Mandatory/Optional: |
optional |
| Introduced API: |
v3.0 |
| Detailed Description: |
It is based on the country of the current mobile network provider the user is roaming in. If not available (e.g iPhone or no SIM card), the app will try to determine the current country based on the GPS location (reverse geo-coding lookup). However this may be unsuccessful and therefore incorrect. |
| Example: |
localCountryCode=UK |
| alt |
integer |
The current altitude of the user. This is not always known on the client and will only be passed when there is a gps fix. |
| Mandatory/Optional: |
optional |
| Introduced API: |
v3.0 |
| Example: |
alt=200 |
| recognizedReferenceImage |
string |
The key(s) of the reference image(s) that caused this layer to show up in the visual search results. |
| Mandatory/Optional: |
optional |
| Introduced API: |
introduced in v6.0; enhanced in v7.0, supports multiple reference image keys. |
| Example: |
If only one reference image in the layer is recognized: recognizedReferenceImage=cheating
If multiple reference images in the layer are recognized, image keys are separated using comma (%2C):
recognizedReferenceImage=cheating%2Cmonkey%2Cbeer |