Layar Connect API Overview
- What is Layar Connect API for ?
- Authenticating with the Connect API
- Possible API server response codes
- How to distinguish between different Layar Connect versions
- How to get an API key ?
What is Layar Connect API for ?
The Layar Connect API allows programmatically reading and writing of layer data. This means a third party software package such as a Layer Management System can remotely create and update layers, without having to scrape the current publishing website.
A developer can give an LMS permission to update/create a layer on his/her behalf with an OAuth token mechanism. The Connect API uses HTTP requests for maximum compatibility and a RESTful interface for clarity.
All operations which developer performs on the layar publishing site can be achieved using the Connect API. For instance, developer can create new layer, get a list of his layers, get layers data, update layers data (minimum_version, category, countries, bounding-boxes, tags, images), delete a layer (not yet implemented), check layer name availability, update layer status (in development to pending review, approved for publication to published, published to unpublished and vice versa, unpublished to frozen and vice versa), get layer change history, etc.
All Connect API responses are JSON formatted with MIME type application/json; charset=utf-8.
POST Requests that contain files (images usually) must be in multipart/form-data format. Otherwise, application/x-www-form-urlencoded is also accepted.
NOTE: The Layar Connect API is not a ready tool for layer development. We just simplify the process of creating new layers by giving you the access to our environment and to developers profiles by making calls from your side to our web service. POIs will also be stored on your side but please make sure that your service is implemented regarding our Developer API. It requires good web technical skills to adopt it.
Authenticating with the Connect API
- 3-legged OAuth
The Layar Connect API uses 3-legged OAuth. Consumer keys and consumer secrets are manually assigned by Layar to selected beta participants. Once a consumer key and secret have been obtained, the following URLs can be used for the OAuth mechanism:
- Request token URL:
- Production: http://www.layar.com/oauth/get_request_token/
- Authorize URL:
- Production: http://www.layar.com/oauth/authorize_request_token/
- Access token URL:
- Production: http://www.layar.com/oauth/get_access_token/
Once the Consumer (LMS) has obtained a valid access token, calls to the API can be made, accompanied by an OAuth signature.
We coded a library and user interface in PHP to help pass 3-legged OAuth and GET data from sandbox or production environment. Set your consumer key and secret in consumer.php. You can change the host in lib/layar/layarpublishingconsumer.php. Please find the files below as attachments.
- PHP library pointing to production: php-oauth-production.zip
- OAuth resources and tools
- Twitter has a great introduction to how OAuth works when accessing an API. The official OAuth specification can be found here.
- There are many open source libraries for all kinds of languages that implement OAuth for you. Google is your friend here.
- A good place to test your OAuth library or implementation is the OAuth Sandbox.
Possible API-server response codes
HTTP 200 - Generic OK status code, request was successful
HTTP 201 - Created
HTTP 204 - Deleted
HTTP 400 - Bad request, invalid data or malformed request
HTTP 401 - Forbidden
HTTP 403 - Forbidden
HTTP 404 - Not found, bad url
HTTP 409 - Duplicate entry
HTTP 503 - Throttled
NOTE: When there is an error 400 or 403 returned, the complete call has failed. The API will verify all incoming data before applying changes. It is possible to make calls to update only parts of a layer, thus getting a response code for each updated part. This makes it easier to determine if a certain input value is valid or invalid. If an LMS does its own input checking, it is also possible to update a layer's attributes in one call.
How to distinguish between different Layar Connect versions
From Layar Connect 2.0, Layar Connect uses call versioning to distinguish between different versions. From Layar Connect 2.0 on, all Layar Connect endpoints start with "/api/connect/[version]/", where [version] should be substituted with the version you wish to call. You may use the wildcard version "latest" if you always intend to call the latest version. Most calls function the same across all versions. If there are differences they are noted in the documentation.
NOTE: Parameters that are introduced in later versions of Layar Connect will generally work in earlier versions as well, if the overarching call was available. For example, the parameter "feature_tracking_enabled" was introduced in Layar Connect 2.0, but because it is part of the get/set layer data call and does not interfere with any previously existing parameters, it will also be available in 1.0 calls. If a parameter acts differently in different Layar Connect versions, it will be documented explicitly.
For reasons of backwards compatibility, the endpoints for calls that were available in Layar Connect 1.0 (not prefixed by "/api/connect/[version]/") will remain available.
The currently recognized versions are "1.0" and "2.0".
How to get an API key ?
In order to use the Connect API, you need to follow the steps below:
- Check out the Connect API and the pricing to see whether it is the right tool for you.
- To use Layar Connect, you will need to apply for an API key. You can do this by filling out the Layar Connect Key request form. You will be contacted by our business development team so that we can work with you to arrange the necessary commercial agreemetn and paperwork. Once it is approved, you will get the key to the production environment. If you have any questions, please contact us through devsupport environment.