API Docs

Developers can use our RESTful API to interact with wheelchair accessible place.

Setup

Before using the Wheelmap API, please read over the Terms of Service and sign up for a user account including an API Key.

Authentication

All requests to the Wheelmap API service require an api key which is passed with every request.

Introduction

The Wheelmap API provides a simple RESTful interface with lightweight JSON-formatted responses to use many of wheelmap.org's website features, including nodes, categories to allow both read and write access. This document provides information to developers on how to integrate with the Wheelmap API.

API Basics

Entry Points

The Wheelmap API has the following entry point:

http://wheelmap.org/api

It is a read-only entry point for public data. It uses the standard parameter api_key for authentication.

Authentication

The Wheelmap API requires an application key that is provided during registration. The key identifies your application to the Wheelmap web service, and is used to track overall call usage. It's passed using the standard api_key parameter. Alternatively the api_key can be submitted via the 'X-API-KEY' HTTP header flag.

API Requests

The Wheelmap API uses a RESTful calling style that works with standard HTTP calls. Any web programming language (PHP, Ruby, Perl, Python, Java, Objective C, C#...) should be able to make and receive HTTP networking calls; consult the documentation for your language of choice.

Request URLs

In a RESTful API, each resource or collection of resources is identified by a unique URL, such as:

http://wheelmap.org/api/nodes/:node_id

URL paths contain the unique IDs of resources. These are identified by a leading colon, as with :node_id above. Before making a call, you must substitute a valid ID value for these placeholders. ID parameters must appear in the URL and cannot be substituted for GET parameters. All ID parameters listed in the URL pattern must be present.

Output Formats

The Wheelmap API handles multiple output formats. Currently, the only supported formats are JSON and XML (see below.) Output formats are selected with a the HTTP Accept header or a specifier that is appended to the URL, like a filename extension:

Format Accept header Specifier Description
JSON application/json .json JavaScript Object Notation
JSONP application/json .json JSON with padding
XML application/xml .xml Extensible Markup Language

JSON is the default, and will be used if nothing is specified. Using the JSON format, the example would look like this:

http://wheelmap.org/api/nodes/:node_id.json

Standard Parameters

Here is a list of standard parameters that are accepted by many or all API methods:

Parameter Type Meaning
api_key string Your API key. Required for all public entry point calls
page integer For pagination, what page of the results you are on. Default is 1.
per_page integer For pagination, how many results to return per page. Default is 200. Max is 500.
callback string Note: For JSONP only! Name of the method you want to call locally with the result of the API

HTTP Methods

RESTful APIs use standard HTTP methods to denote actions against a resource:

202 means: The request has been accepted for processing, but the processing has not been completed. The reason why POST and PUT method return the rather unknown status code 202 is, because the update/create operation is not processed immediately. The command will be put on a job queue. Chances are that something goes wrong while execution after the POST/PUT request has been finished.

Because some toolkits lack support for PUT and DELETE (most notably JavaScript) you can use method overloading to fake an HTTP method. Use a POST call and append the standard method parameter:

http://wheelmap.org/api/nodes/:node_id?_method=put

API Responses

JSON Data

Data is returned using JSON, a lightweight serialization language that is compatible with many different languages. JSON is also syntactically correct JavaScript code, which means that it can be parsed with JavaScript's own eval() function.

Standard Response Format

Each API response is wrapped in a standard structure that holds the results of the API call, plus metadata about the request:

{
  "conditions": {
    "format": "json"
  },
  "meta": {
    "item_count":2,
    "item_count_total":5930
  },
  "results": [
    { result object }
  ]
}

JSONP Data

The Data is returned using JSON, but the return value is wrapped in a JavaScript method call. The first argument to the method is the result of the API call, the second is the API Response Code. This makes it easy to check, if the call was successfull, or not.

callback({
  "conditions": {
    "format": "json"
  },
  "meta": {
    "item_count":2,
    "item_count_total":5930
  },
  "results": [
    { result object }
  ]
}, 200)

conditions

conditions echoes the parameters that were passed into the request. This could be filters, format, pagination and so on.

meta

meta specifies meta information page and total number of pages, entries per page and so on.

results

results is an array of objects. For consistency's sake, it is always an array, even if only one result is expected.

API Response Codes:

The Wheelmap API will return a status code upon every request. The following status codes could possibly returned.

Code Meaning Description
200 OK (application/json) The server serverd the request successfully
202 Accepted (application/json) The request has been accepted for processing, but the processing has not been completed.
400 Bad Request (application/json) The server could not understand your request. Verify that request parameters (and content, if any) are valid.
401 Authorization Required (application/json) Authentication failed or was not provided. Verify that you have sent valid credentials via an api_key parameter. A 'Www-Authenticate' challenge header will be sent with this type of error response.
403 Forbidden (application/json) The server understood your request and verified your credentials, but you are not allowed to perform the requested action.
404 Not Found (application/json) The resource that you requested does not exist. Verify that any object id provided is valid.
406 Not Acceptable (application/json) The resource identified by the request is only capable of generating a desired response. In fact it means the requested content type is not available. Try JSON or XML.
500 Internal Server Error (application/json) An unknown error has occurred. When possible, an error message will be returned describing the error.
503 Temporarily not available The wheelmap service is currently not available. This usually happens when we have to do maintainenance tasks. Please make sure your client is ready to react on this status gracefully as it makes for a good user experience. We try to minimize these kind of downtimes but some are not avoidable.

API Error Messages

If the API responds with an HTTP status code with 400 or higher, there will be a descriptive error message. Please make sure your client can handle error codes and display this message to the client.

Resources