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.
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
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.
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
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.
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
- id - Return a specific site by site id
- q - Search term
- tw - Thumbnail width
- th - Thumbnail height
- cat - Display category listing instead of search results when set to “all”
- return_vars - Comma separated list of variables to return (see list below)
- lat - When searching, latitude to search from
- lon - When searching, longitude to search from
- distance - Distance in miles or km (must specify “km” in the units var if km)
- units - Pass “km” if distance is in kilometers and not miles
- category_id - Search by specific category id
- minpopularity - Set this integer as the minimum number of unique visitors a site must get over the period of the past 7 days to be returned. Default is 0, allowing all deployments to be returned.
- has_description - Return only deployments that have descriptions
- no_description - Return deployments that do not have a description
- has_ss - Return deployments that have screenshots / photos
- limit - Works just like MySQL limit. Accepts one positive integer or two, comma separated.
- id - Site ID
- name - Deployment name
- url - URL for the deployment
- description - Admin defined description of what the deployment is about. No text limit imposed here.
- category_id - ID of the category. To get the name of the category, follow instructions above.
- latitude - The center of the map of the deployment (lon).
- longitude - The center of the map of the deployment (lat).
- discovery_date - The date the deployment saw the light of day.
- ss1 - URL to full size image.
- ss2 - URL to full size image.
- ss3 - URL to full size image.
- ss4 - URL to full size image.
- ss5 - URL to full size image.
- ss1_t - URL to dynamically generated thumbnail of ss1.
- ss2_t - URL to dynamically generated thumbnail of ss2.
- ss3_t - URL to dynamically generated thumbnail of ss3.
- ss4_t - URL to dynamically generated thumbnail of ss4.
- ss5_t - URL to dynamically generated thumbnail of ss5.
- distance - Distance from passed lat,lon when doing a search, in miles. This only shows up if you are doing a search by distance from lat,