Skip to content

API for Filtering

Jump to bottom Edit New page
Gustavo Giráldez edited this page May 9, 2016 · 5 revisions

Note: all these examples assume you have an Collection ID of 350.

Filtering

You can apply filter criteria like this:

/api/collections/350.json?beds=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 paginated by Resourcemap. Each page contains 50 results. To get the first page of a collection you can submit:

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

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

{
    "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 to retrieve 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, US:

  • /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

You can also specify the radius in kilometers (km) and miles (mi), so all these are equivalent:

  • /api/collections/350.json?lat=40.7142691&lng=-74.0059729&radius=10000
  • /api/collections/350.json?lat=40.7142691&lng=-74.0059729&radius=10km
  • /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 to 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 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 "starts with" operator.

For example:

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

If your collection has 3 sites:

  • Site 1 with mgr "Mr. Paul"
  • Site 2 with mgr "Mr. Patrick"
  • Site 3 with mgr "Mr. Peter"

then your query will return sites 1 and 2.

Filtering by date range

For Date fields you can query by date range. For example, given a last_visit field:

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

will filter sites where last_visit is between 10/01/2012 and 10/31/2012 inclusive.

To query for a specific date use the same date for start and end in the range:

  • ?last_visit==10/01/2012,10/01/2012

will filter sites with last_visit on 10/01/2012.

Note: date format for Date fields is mm/dd/yyyy

Filtering by Hierarchy field

To query by hierarchy fields, use the hierarchy ID, since the name might be duplicated in several nodes.

  • ?admin_unit[under]=sud

This will return 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 filter by multiple hierarchy values 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 query using the option's code:

  • ?color=red

Filtering by site reference

For querying 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 last time the site was updated using the updated_since parameter:

  • /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

Filtering by creation time

You can filter by the time the site was created using the created_since parameter:

  • /api/collections/350.json?created_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?created_since=2012-03-28T07:57:56
  • With time zone: /api/collections/350.json?created_since=2012-03-28T06:57:56+01:00

Filtering by deleted time

You can filter by the time the site was deleted using the deleted_since parameter:

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

This will return sites that were deleted after March 26th 2012. This is the only way to query deleted sites, all other queries return non-deleted sites.

As with updated_since above, the since date is expressed in ISO-8601 so it supports time and timezone options as well:

  • With time: /api/collections/350.json?deleted_since=2012-03-28T07:57:56
  • With time zone: /api/collections/350.json?deleted_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 the field name 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 querying:

  • /api/collections/350/count.json
Add a custom footer
Add a custom sidebar
Clone this wiki locally