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.