Developer's API Documentation : Saved Search

Overview

Toodledo has a powerful search page that allows you to easily construct simple or complex search criteria that will find matching tasks. Once you have made the perfect search, you can save it for quick access on return visits. This API provides access to saved searches created by your users. For more information about saved searches, please read our documentation.

A search consists of a number of rules. These rules can be root level rules or they can be grouped rules. Rules are joined with boolean operators. In this example, rule1 and rule2 are root level rules and rule3 and rule4 are rules inside a group. Grouping rules switches the boolean operator. In this way, complex searches can be constructed.

rule1 AND rule2 AND (rule3 OR rule4).

Retrieving Searches

You can fetch all of the user's saved searches by making a GET request to the /tasks/search.php API call.

http://api.toodledo.com/3/tasks/search.php?access_token=yourtoken

This will return a JSON encoded list of the user's saved searches.

JSON: 
[
  {"id":1234,"name":"MySearch","bool":"All",
    "search":{
      "root":[
        {"field":"checked","type":"no","value":""},
        {"field":"title","type":"contains","value":"laundry"}
      ],
      "1":[
        {"field":"tag","type":"is","value":"tag"},
        {"field":"folder","type":"is not","value":"12345"}
      ]
    }
  },
  {"id":1235,"name":"Another Search","bool":"Any", 
    "search":{
      "root":[
        {"field":"checked","type":"yes","value":""},
        {"field":"tag","type":"does not contain","value":"urgent"}
      ]}
  }
]

You can also specify xml as the output format for any API calls by attaching "f=xml" to the URL.

http://api.toodledo.com/3/tasks/search.php?access_token=yourtoken&f=xml

XML: 
<searches>
  <search>
    <id>1234</id><name>MySearch</name><bool>All</bool>
    <root>
      <rule><field>checked</field><type>no</type><value></value></rule>
      <rule><field>title</field><type>contains</type><value>laundry</value></rule>
    </root>
    <group>
      <rule><field>tag</field><type>is</type><value>tag</value></rule>
      <rule><field>folder</field><type>is not</type><value>12345</value></rule>
    </group>
  </search>
  <search>
    <id>1235</id>
    <name>Another Search</name>
    <bool>Any</bool>
    <root>
      <rule><field>checked</field><type>yes</type><value></value></rule>
      <rule><field>tag</field><type>does not contains</type><value>urgent</value></rule>
    </root>
  </search>
</searches>

Explanation of result terms:

id : The id number of the saved search. This is unique per user, but two different users may have different searches with the same id.
name : The display name for the saved search, up to 32 characters.
bool : Indicates the state of the "Match" option for a search. There are two possible values. "All" means that all the root rules and groups must match (The outer boolean will be AND and the inner boolean will be OR). "Any" means that only one of the root rules or groups must match (The outer boolean will be OR and the inner boolean will be AND).
search : In the JSON return format, this contains the nested rules for the saved search. Each group will have a numerical index (which may or may not be consecutive). Order does not matter.
root : An array of root level rules.
group : In the XML return format, this contains an array of grouped rules.
field : The name of the field being inspected (see below).
type : The type of search being performed (see below).
value : The value to search with.

Field Names

addedby : The user id of the collaborator who assigned the task
attachment : Does the task have an attachment
checked : Whether the task is completed or not
context : The task's context
added : The date the task was aded
completed : The date the task was completed
modified : The date the task was modified
duedate : The task's due date
duetime : The task's due time
folder : The task's folder
goal : The task's goal
length : The task's length
location : The task's location
note : The task's note
parent : Is it a parent
priority : The task's priority
remind : Does the task have a reminder/alarm
repeat : The task's repeat value
shared : Is the task shared
star : The task's star
startdate : The task's start date
starttime : The task's start time
status : The task's status
subtask : Is it a subtask
tag : The task's tag
title : The task's title
timer : The task's timer
via : How the task was added. These are the possible values:
- 0: Main website
- 1: Email Import
- 2: Firefox Addon
- 3: This API
- 4: Widgets (Google Gadget, etc)
- 5: Not used
- 6: Mobile Phone
- 7: iPhone App
- 8: Import Tools
- 9: Twitter

Search Types

contains : Matches a string if it contains this substring
yes : Boolean true
is : Exact value match
begins with : Matches a string if it starts with this substring
ends with : Matches a string if it ends with this substring
does not contain : Matches a string if it does not contain this substring
no : Boolean false
is not : Exact value mismatch
is after : Matches a date if it comes after this value
is more than : Matches a number if it comes after this value
is before : Matches a date if it comes before this value
is less than : Matches a number if it comes before this value
was in the last : Matches a date if it was in the last X days
was not in the last : Matches a date if it was not in the last X days
is in the next : Matches a date if it is in the next X days
is not in the next : Matches a date if it is not in the next X days
is in : Matches a date if it is in exactly X days
is not in : Matches a date if it is not in exactly X days
was : Matches a date if it was exactly X days ago
was not : Matches a date if it was not exactly X days ago
exists : Matches if the field has a non-zero value
does not exist : Matches if the field is empty or zero

Error Codes

Any of the API calls can return error messages. The saved search calls may return some of the general error codes.