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.
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.
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.
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
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
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
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
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
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
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)
Additional fields: report count, deployment version.
Only return “active” deployments.
Have paging so you don't have to return every result.
Request Vars
Returned Vars