JourneyApps API - Docs & Resources

Queries (Filtering Retrieved Objects)

This function allows you to retrieve a list of objects matching specified criteria.

Relative URL	HTTP Request Method
/api/v1/object-type.format?query[attribute]=value	GET
/api/v1/object-type.format?q[attribute]=value	GET
/api/v1/object-type.format?query[attribute]=value1&query[other_attribute]=value2	GET

Note: Replace object-type with the type of object that you wish to retrieve (as defined in your app's Data Model), for example 'person', 'job' or 'asset'. Replace format with the response data format (json or xml), or leave it out. Multiple query criteria can be specified.

Parameters

Query parameters are specified as a URL-encoded query or q hash. Valid keys for this hash are names of the attributes in that object-type. The format for the values are the same as for creating objects. Please refer to the same section at Creating New Objects.

You can specify your criteria with logic such as 'equals', 'not equal to', 'greater than', 'less than', etc. as follows:

Comparison	Syntax	Allowed Values
Attribute Equals	query[attribute]=value
Attribute is Not Equal To	query[attribute.ne]=value
Attribute is Less Than	query[attribute.lt]=value
Attribute is Less Than or Equal To	query[attribute.lte]=value
Attribute is Greater Than	query[attribute.gt]=value
Attribute is Greater Than or Equal To	query[attribute.gte]=value
Attribute Contains	query[attribute.contains]=value
Attribute is Null (or Not Null)	query[attribute.null]=value	Specify `true` for the value to check for "Is Null" or `false` to check for "Is Not Null"

Response

The response includes a list of all the objects of the given type which match all of the query criteria. The format of the objects is the same as for listing all objects (please refer to the Retrieving All Objects section.)

Examples

Note: When using curl with queries you have to either escape the square brackets with a backslash (\[) or add the -g option to turn off curl's globbing functionality

Match a string attribute

curl https://run-testing.journeyapps.com/api/v1/assets.json?q[serial_number]=123456 \
     -g -u '503b783fd6fb307677000006:nKXd8v54R9W3aE_qTo4-'

Match multiple attributes, including human-readable dates

curl https://run-testing.journeyapps.com/api/v1/assets.json?q[make]=Acme&q[registration_date]=2012-09-19 \
     -g -u '503b783fd6fb307677000006:nKXd8v54R9W3aE_qTo4-'

Query with datetimes in ISO8601 format

curl https://run-testing.journeyapps.com/api/v1/assets.json?q[_updated_at]=2012-09-18T10:27:46Z \
     -g -u '503b783fd6fb307677000006:nKXd8v54R9W3aE_qTo4-'

Match a value (as a string) from an enum

curl https://run-testing.journeyapps.com/api/v1/assets.json?q[make]=Acme&q[verified]=no \
     -g -u '503b783fd6fb307677000006:nKXd8v54R9W3aE_qTo4-'

Query on a relationship - Find all assets related to the specified room.

curl https://run-testing.journeyapps.com/api/v1/assets.json?q[room_id]=8af9f570-017b-11e2-84c8-b88d120322de \
     -g -u '503b783fd6fb307677000006:nKXd8v54R9W3aE_qTo4-'

Searching Across All Attributes

You can also search through all the attributes of all objects of a given type for a partial text match. This can be useful for implementing basic search functions.

Relative URL	HTTP Request Method
*/api/v1/object-type/search*.format	POST

Parameters

The search text must be specified as a URL-encoded parameter named query.

Example

Search task objects for the text "First":

curl https://run-testing.journeyapps.com/api/v1/tasks/search.json \
     -u '533bda53027894f69b001055:7Ajj5htRY1uzw7b4w23V' \
     -d 'query=First'

Response:

[
  {
    "_updated_at": "2014-04-02T09:38:57Z",
    "instructions": "Please fill in document A",
    "name": "My First Task",
    "status": 1,
    "id": "9cf54818-ba4a-11e3-a567-001e6733fe3c",
    "display_name": "My First Task",
    "display_attachments": {
    }
  },
  {
    "_updated_at": "2014-04-02T09:40:02Z",
    "instructions": "Please fill in document A",
    "name": "My First Task",
    "status": 1,
    "id": "c3d3db52-ba4a-11e3-a567-001e6733fe3c",
    "display_name": "My First Task",
    "display_attachments": {
    }
  }
]

Next Section: 8. Sorting

Previous Section Next Section

The JourneyApps API (V1) → 7. Queries/Filtering & Searching

Queries (Filtering Retrieved Objects)

Parameters

Response

Examples

Searching Across All Attributes

Parameters

Example