API for Filtering

Note: For these examples we will assume you have an Collection ID of 350

Filtering

You can apply filter criteria like this:

/api/collections/350.json?NUMBEDS=20

Note: if you are filtering by a lookup field, the lookup parameter you must use is the Code of the option and not the label.

Pagination

Results are returned by page. 50 results are returned per page. To get the first page of a collection you can submit

/api/collections/350.json?page=1

The total amount of pages is returned in the response as totalPages in the response. The total amount of sites is returned as count.

{
    "name": "Hospitals",
    "count": 230,
    "totalPages": 5,
    "nextPage": "http://resourcemap.instedd.org/api/collections/350.json?page=2",
    "sites": [ ... ]
}

In this scenario the following request will eventually retrieve all the sites.

• /api/collections/350.json?page=2
• /api/collections/350.json?page=3
• /api/collections/350.json?page=4
• /api/collections/350.json?page=5

When available, each response will contain also nextPage and previousPage field with the URL of the next and previous page. This can be used as an alternative to iterate through all pages.

{
    "nextPage": "http://resourcemap.instedd.org/api/collections/350.json?page=3",
    "previousPage": "http://resourcemap.instedd.org/api/collections/350.json?page=1",
}

Pagination can be used together with any filter option listed below.

Filter by Location

(Note: this works exactly the same as Google Maps API)

To define a bounding box, pass box=west,south,east,north, where each boundary defines the latitude (north, south) or longitude (east,west) of the bounding box.

The following example restricts a search to (roughly) Colorado:

• /api/collections/350.json?box=-109,37,-102,41

To define a circular area, pass a center location within the lat and lng parameters, and a radius in meters.

The following example restricts a search to within 10 kilometers of New York's City Hall:

• /api/collections/350.json?lat=40.7142691&lng=-74.0059729&radius=10000

Another way to specify the previous search:

• /api/collections/350.json?lat=40.7142691&lng=-74.0059729&radius=10km

Or even:

• /api/collections/350.json?lat=40.7142691&lng=-74.0059729&radius=6.21mi

"km" and "mi" are the only units supported.

Location Missing

For filtering sites with no location use:

• ?location_missing=true

Filtering by yes/no property

You can use "yes", "true" or "1" to mean "yes", and any other values will mean "no".

For example:

• ?available=yes: filters by the property 'available' having the value 'yes'

• ?available=true: filters by the property 'available' having the value 'yes'

• ?available=1: filters by the property 'available' having the value 'yes'

• ?available=no: filters by the property 'available' having the value 'no'

Filtering by numeric property

You can query by any numeric field with the = operator and also use other operators like <, <=, =>, >.

For example:

• ?beds=10: filters by the property 'beds' equal to 10

• ?beds=>10: filters by the property 'beds' greater than 10

• ?beds=>=10: filters by the property 'beds' greater or equal to 10

• ?beds=<10: filters by the property 'beds' less than 10

• ?beds=<=10: filters by the property 'beds' less than or equal to 10

Note: the operators always need to come after "beds=" which means an extra equal sign before the actual comparison operator. This may look confusing at a first glance.

Filtering by text property

You can query by any Text, User and Email Fields using the "start with" operator.

For example:

• ?mgr=~=Mr. Pa: filters by property 'mgr' starting with "Mr. Pa".

If your collection have 3 sites:

Site 1 with mgr=Mr. Paul

Site 2 with mgr=Mr. Patrick

Site 3 with mgr=Mr. Peter

Your query will filter sites 1 and 2.

Filtering by date range

For Date Fields you can query by date range:

• ?creation==10/01/2012,10/31/2012

This will filter sites where creation is between 10/01/2012 and 10/31/2012, included.

For queries for a specific date you can use the same date for start and end range:

• ?creation==10/01/2012,10/01/2012 : filters sites with creation = 10/01/2012

Note that date format is mm/dd/yyyy

Filtering by Hierarchy field

You can query hierarchy fields using hierarchy ID, since the hierarchy name might be duplicated in several nodes.

• ?admin_unit[under]=sud

This will bring the sites which has the admin_unit field set to a value of 'sud' (or a descendant of 'sud') in the hierarchy.

If you want to filter sites whose admin_unit field has a value that exactly matches something, you have to do it like this:

• ?admin_unit[]=sud

You can 'or' those by accumulating them like this:

• ?admin_unit[]=sud&admin_unit[]=east

Filtering by option fields

For fields with kind Select One or Select Many, you can query using the option's code:

• ?color=red

You can also filter using the option's label:

• ?color=Red

Filtering by site reference

For query Site Fields you need to use the referred site internal id.

• ?health_training_reference=1234

Note: The ID field is the internal system ID of the item, not some field you created and treat as an ID field.

Filtering by updated time

You can filter by the time the item was updated this way:

• /api/collections/350.json?updated_since=2012-03-26

Date format is expressed in ISO-8601 so it supports time and timezone options as well:

With time: /api/collections/350.json?updated\_since=2012-03-28T07:57:56

With time zone: /api/collections/350.json?updated\_since=2012-03-28T06:57:56+01:00

Full-text search

Full-text search includes all values, and codes and values of lookup fields.

• /api/collections/350.json?search=Sunshine

Filtering by reserved fields

To filter by reserved fields (suppose you have fields named "page", "group" or "updated_since"), you have to prefix with an "@". For example, to filter by a field coded "updated_since" you would do:

• /api/collections/350.json?@updated_since=2012-03-26

Combining filters

To apply filters in multiple fields you should put them one after another, separated by &:

• ?color=red&admin_unit[]=Sud&updated_since=2012-03-26

Counting Sites

You can count sites by calling:

• /api/collections/350/count.json