Developer's API Documentation : Locations

Overview

Locations are a way to organize tasks by where they can be completed.

Jump To:

Retrieving Locations
Adding Locations
Editing Locations
Deleting Locations
Errors

Syncing

Syncing locations is fairly straight forward. The first thing to do is add any new locations you have created and delete any locations that you have deleted. Then, look at the "lastedit_location" timestamp returned from Account Info to determine if any changes have happened on the server since the last time you synced. If yes, then you need to fetch the locations from the server and integrate this into your local copy. This is where you would do conflict resolution if a location was edited in both places. After this, if you have any locations that you edited, you can send these edits up to the server.

Retrieving Locations

The "locations/get.php" API call will return a list of your locations with their names and id numbers. You can access this via GET or POST.

http://api.toodledo.com/3/locations/get.php?access_token=yourtoken

This call will return a JSON encoded object that looks like this.

[{"id":123,"name":"Work","description":"123 Main Street","lat":12.345,"lon":-45.678},
{"id":456,"name":"Home","description":"","lat":13.345,"lon":-42.678},
{"id":789,"name":"Car","description":"","lat":0.0,"lon":0.0}]

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/locations/get.php?access_token=yourtoken&f=xml

<locations>
	<location>
		<id>123</id><lat>12.345</lat><lon>-45.678</lon>
		<name>Work</name><description>123 Main Street</description>
	</location>
	<location>
		<id>456</id><lat>13.345</lat><lon>-42.678</lon>
		<name>Home</name><description></description>
	</location>
</locations>

Adding Locations

Add a location using the "locations/add.php" API call. You can access this via POST. Location names must be unique within an account. If you try to add a location that already exists, you'll get an error. Each user can have up to 500 locations. If you try to add more than this, you will get an error.

name : A text string up to 64 characters. (required)
description : A text string up to 255 characters used to describe the locaiton (address, phone number, hours of operation, etc). (optional)
lat : A decimal representing the latitude. (optional)
lon : A decimal representing the longitude. (optional)

http://api.toodledo.com/3/locations/add.php
	name=MyLocation
	lat=45.678
	lon=-123.456
	access_token=yourtoken

If the add was successful the new location will be returned.

[{"id":12345,"name":"MyLocation","description":"","lat":45.678,"lon":-123.456}]

<locations>
	<location>
		<id><lat>45.678</lat><lon>-123.45</lon></id>
		<name>MyLocation</name><description></description>
	</location>
</locations>

Editing Locations

Edit a location using the "locations/edit.php" API call. You can access this via POST. Location names must be unique within an account. If you try to edit the location name to one that already exists, you will get an error. If you try to edit the location, but pass in the same values that already exist on the server, you will get an error. You should avoid making unnecessary edits.

id : The id number of the location to edit. (required)
name : A text string up to 64 characters. (optional)
description : A text string up to 255 characters used to describe the locaiton (address, phone number, hours of operation, etc). (optional)
lat : A decimal representing the latitude. (optional)
lon : A decimal representing the longitude. (optional)

http://api.toodledo.com/3/locations/edit.php
	id=12345
	name=MyLocation
	access_token=yourtoken

If the edit was successful the edited location will be returned.

[{"id":12345,"name":"MyLocation","description":"","lat":45.678,"lon":-123.456}]

<locations>
	<location>
		<id><lat>45.678</lat><lon>-123.45</lon></id>
		<name>MyLocation</name><description></description>
	</location>
</locations>

Deleting Locations

The "locations/delete.php" API call will allow you to permanently delete a location. You can access this via POST. Any tasks that have this location will have their location set to "none".

id : The id number of the location to delete. (required)

http://api.toodledo.com/3/locations/delete.php
id=12345
access_token=yourtoken

If the delete was successful you will get the following message.

{"deleted":12345}

<deleted>12345</deleted>

Error Codes

Any of the API calls can return error messages. Here is a list of the error messages that you may receive from the locations API endpoints. If there was an error when editing or deleting a location, the id number that you attempted to edit will be included in the error's "ref" field for your reference.

501 : Your location must have a name.
502 : A location with that name already exists.
503 : Max locations reached (500).
504 : Empty id.
505 : Invalid location.
506 : Nothing was edited.

Examples:

{"errorCode":502,"errorDesc":"A location with that name already exists","ref":1234}

<error id="502" ref="1234">A location with that name already exists</error>