This document covers the features and options surrounding the public deployment search API. This API is a listing of all sites that have opted in to be listed publicly so that their deployments may be easier to find on websites, mobile applications and other tools.

Intention

The reason we put this API together was so that the Community Website could feature deployments while giving administrators a way to manage the publicly facing information about their deployment. Beyond the website, the API is being developed to facilitate a more user friendly experience on the iPhone and Android applications when connecting to a deployment. No longer will a user have to know the URL for deployments that are listed publicly.

Accessing the API

The REST API returns JSON and can be accessed at the following URL: http://tracker.ushahidi.com/list/

By hitting this URL, you will be returned every deployment that has opted in. We kindly ask that you refrain from accessing the API this way unless you intend on caching the results. Instead, use the search features to limit the number of results being returned.

Searching the API by Keyword

The API includes basic search functionality that does a plaintext, wildcard search

 

 

{search_term}

 

on the URL and notes fields. This can be accessed with the “q” GET variable.

 

Example Query: http://tracker.ushahidi.com/list/?q=haiti

Searching the API by Location

You have the ability to find publicly listed deployments by distance from a specific latitude and longitude in miles or kilometers. When searching using this method, you will have the option to return the distance along with the normal returned set of data. When performing this search, you must pass the following variables: lat, lon, distance and optionally, units. The lat, lon variables are the point you are searching from. The distance is the distance from this point in miles. Not everyone understands miles so you also have the option to search using kilometers. This is done by simply passing 'km' with the units variable and the API will convert this value to miles for you. Keep in mind that the value returned with distance is in miles and not kilometers, regardless of the units you pass to the API.

Example Query: http://tracker.ushahidi.com/list/?lat=55.3&lon=-3.4&distance=100&units=km

Searching the API by Category

You can filter your results by the category a deployment has listed itself as. Use the “category_id” variable for this. Refer to the Categories section to get the list of categories with their corresponding ids.

Example Query: http://tracker.ushahidi.com/list/?category_id=12

Images and Thumbnails

The API returns a set of images that are defined by the user. There are a maximum of five images defined but currently, they are only being prompted to upload a maximum of four images. These can be accessed via the ss1, ss2, ss3, ss4 and ss5 variables. Thumbnails are accessible via the ss1_t, ss2_t, etc variables. The thumbnails are generated dynamically and will be resized and cropped to your specifications. Simply add the “tw” and “th” GET variables to modify the width and height in pixels. Please note, you must have both “tw” and “th” set for either of them to have an effect.

Example Query: http://tracker.ushahidi.com/list/?q=haiti&tw=100&th=100

Categories

All deployments are assigned a category and it's identified by an id in the standard result set. To get the corresponding names for these IDs, simply hit: http://tracker.ushahidi.com/list/?cat=all

If you would like to just get the details for one specific ID, use the same “cat” variable but instead use the ID of that category.

Example Query: http://tracker.ushahidi.com/list/?cat=4

Limit Response Variables Returned

In general, you don't want to pull every possible piece of information about all public deployment (at the time of this writing, the json is 1.3MB). To limit your response to just the bits of data you would like, use the return_vars variable in your request.

Example Query: http://tracker.ushahidi.com/list/?return_vars=name,latitude,longitude

Limit Number of Results / Pagination

In order to return just a subset of the entire result set you are looking for, use the limit variable. It uses MySQL logic, just like you would use it in a SQL statement.

Example Query: http://tracker.ushahidi.com/list/?limit=5,10 (returns 10 results, starting with the 6th record)

Example Query: http://tracker.ushahidi.com/list/?limit=100 (returns first 100 results)

Future Functionality / To Do

Additional fields: report count, deployment version.

Only return “active” deployments.

Have paging so you don't have to return every result.

Glossary of Variables

Request Vars

Returned Vars