API Documentation - Guide

LocalWiki: An API for your city.Our dream is for LocalWiki to not only be the best way to learn and share knowledge about your local community, but also to be a platform upon which a countless civic and locally-relevant applications will be built. In the same way that OpenStreetMap has become a platform for open, cartographic knowledge, we hope that LocalWiki can become an open, global platform for local knowledge and human experience--places, people, neighborhoods,...everything!

Overview

LocalWiki provides a RESTful, read/write API with advanced geospatial capabilities. Reading (using GET requests) is allowed for all users, but to write (POST, PUT, PATCH, DELETE) you’ll need to get an API key.

The API root is at https://localwiki.org/api/v4/

Viewing the API root in a web browser will show you an interactive, hyperlinked API view that will [under construction]

We assume that you're somewhat familiar with how REST-style web APIs work. It should be easy to interact with the API using any standard HTTP library. That said, there are some wrapper libraries available for various programming languages and environments.

Paginating result sets

You can paginate through a result set by following the next and previous URIs. You can change the number of results returned by a query by providing the limit query parameter (maximum 100).

Filtering result sets

Result sets can be filtered by providing one of the filter fields specified in the endpoint description, which can be found by viewing the API in a browser or issuing an OPTIONS request. All filter values should be url encoded.

Excluding fields from results

For latency reasons, it's sometimes good to just get a subset of fields back in a result set. You can limit the result set to just a set of fields by providing the fields parameter, which should be set to a comma-separated list of field names. Note that this only applies to GET requests.

Ordering result sets

Where applicable, result sets can be ordered by providing an ordering query parameter. The options for the ordering parameter can be found by viewing a resource endpoint in a browser or issuing an OPTIONS request.

Standard lookup types

Some fields support further filtering using the standard lookup types. The value of the filter will depend on the datatype being filtered against.

Not all fields allow these lookups, but for those that do, they are:

exact -- Exact match.
iexact -- Case-insensitive exact match.
contains -- Case-sensitive containment test.
icontains -- Case-insensitive containment test.
gt -- Greater than.
gte -- Greater than or equal to.
lt -- Less than.
lte -- Less than or equal to.
startswith -- Case-sensitive starts-with.
istartswith -- Case-insensitive starts-with.
endswith -- Case-sensitive ends-with.
iendswith -- Case-insensitive starts-with.
isnull -- Takes either True or False.
regex -- Case-sensitive regular expression match.
iregex -- Case-insensitive regular expression match.

Not all lookups are supported on all types (e.g. icontains doesn't make much sense on a date field).

Examples

Find all users with a username that starts with "doge", case-insensitive:

/api/users/?username__istartswith=doge

Find all page history for pages that have been edited before 2014-01-16T00:00:00.0:

/api/pages_history/?history_date__lt=2014-01-16T00:00:00.0

More examples can be found in the API examples documentation.

Geographic lookup types

Some fields support further filtering using the geographic lookup types.

The value of the filter should be provided in GeoJSON geometry object -- not as part of a FeatureCollection.

Not all fields allow these lookups, but for those that do, they are:

bbcontains -- Tests if the geometry field’s bounding box completely contains the lookup geometry’s bounding box.
bboverlaps -- Tests if the geometry field’s bounding box overlaps the lookup geometry’s bounding box.
contained -- Tests if the geometry field’s bounding box is completely contained by the lookup geometry’s bounding box.
contains -- Tests if the geometry field spatially contains the lookup geometry.
contains_properly -- Returns true if the lookup geometry intersects the interior of the geometry field, but not the boundary (or exterior).
coveredby -- Tests if no point in the geometry field is outside the lookup geometry.
covers -- Tests if no point in the lookup geometry is outside the geometry field.
crosses -- Tests if the geometry field spatially crosses the lookup geometry.
disjoint -- Tests if the geometry field is spatially disjoint from the lookup geometry.
equals
exact, same_as
intersects -- Tests if the geometry field spatially intersects the lookup geometry.
overlaps
touches -- Tests if the geometry field spatially touches the lookup geometry.
within -- Tests if the geometry field is spatially within the lookup geometry.
left -- Tests if the geometry field’s bounding box is strictly to the left of the lookup geometry’s bounding box.
right -- Tests if the geometry field’s bounding box is strictly to the right of the lookup geometry’s bounding box.
overlaps_left -- Tests if the geometry field’s bounding box overlaps or is to the left of the lookup geometry’s bounding box.
overlaps_right -- Tests if the geometry field’s bounding box overlaps or is to the right of the lookup geometry’s bounding box.
overlaps_above -- Tests if the geometry field’s bounding box overlaps or is above the lookup geometry’s bounding box.
overlaps_below -- Tests if the geometry field’s bounding box overlaps or is below the lookup geometry’s bounding box.
strictly_above -- Tests if the geometry field’s bounding box is strictly above the lookup geometry’s bounding box.
strictly_below -- Tests if the geometry field’s bounding box is strictly below the lookup geometry’s bounding box.
isnull --Takes either True or False.

Examples

Find all maps have a polygon that lays within an area of Mexico:

/api/maps/?polys__within={ "type": "Polygon", "coordinates": [ [ [ -117.22412109375, 24.347096633808512 ], [ -117.22412109375, 32.43561304116276 ], [ -102.9638671875, 32.43561304116276 ], [ -102.9638671875, 24.347096633808512 ], [ -117.22412109375, 24.347096633808512 ] ] ] }

Find maps that have a polygon that contains a point in the middle of San Francisco:

/api/maps/?polys__contains={ "type": "Point", "coordinates": [ -122.44674682617188, 37.76745803822967 ] }

Find maps that have a point inside of San Francisco:

/api/maps/?points__within={ "type": "Polygon", "coordinates": [ [ [ -122.51575469970703, 37.78781006166096 ], [ -122.50202178955078, 37.708541298593325 ], [ -122.37911224365234, 37.70881291183666 ], [ -122.37808227539061, 37.761487048570935 ], [ -122.3818588256836, 37.790794553924414 ], [ -122.40726470947266, 37.81493737606794 ], [ -122.47764587402344, 37.81059767530207 ], [ -122.51575469970703, 37.78781006166096 ] ] ] }

More examples can be found in the API examples documentation.

Historical resources

All editable resources (pages, maps, etc) have associated historical resources, which record their version history.

The history_type attribute can be one of:

0 - Added
1 - Updated
2 - Deleted
3 - Deleted via cascade
4 - Reverted
5 - Reverted/Added
6 - Reverted/Deleted
7 - Reverted/Deleted via cascade
8 - Reverted via cascade

Uploading files via the API

To upload a file, you'll want to POST/ PUT /PATCH to the /files/ resource. You will need to make a multipart/form-data request to send a file. You should send the file as the file attribute (as named in the resource) of the form. You will also need to send a name attribute containing the desired file name.

Getting an API key

You do not need an API key to read from the API, but you will need an API key to write. Go here to apply for an API key.

We will eventually support more user-centric API authentication using OAuth which will be more ideal for e.g. wrapper applications.

LocalWiki API wrapper libraries

Python

If you’re using Python, we recommend you check out the small and simple slumber library, which makes it really easy to work with RESTful APIs like the LocalWiki API. Here’s some examples using slumber with the LocalWiki API:

PUT EXAMPLE HERE

Ruby

Work has begun on a Ruby API client. Check it out at https://github.com/codeforseattle/localwiki_client. It’s in a very early stage at this point, so you may want to help with its development! Note: the client is currently out of date and won't work with the current version of the LocalWiki API. It needs updating!

JavaScript

Work has begun on a JavaScript API client. Check it out at https://github.com/codeforseattle/node-localwiki-client.

A guide to learning about web APIs with the LocalWiki API can be found here.

Alternative ways to access the data

If you are not a programmer, you can also make use of our API simply by calling the URLs. Data is returned in JSON format which can be converted to other formats such as: