List of Zones
The zones are defined on the Vancouver city website. There are 2 schedules: North and South.
The API lists the available zones at:
- /zones -
text/html - /zones.txt -
text/plain - /zones.json -
application/json
Zone Data
Each zone has its own resource page. Right now it is very simple, but more data could be added.
The zone names are listed at /zones, and the URL will look like:
This data is also available as text/plain
and application/json.
Each zone has several pieces of data available:
- Pickup Days - The list of pickup days for the zone
- Next Pickup - The next pickup day for this zone
- Next Day of Week Change - The next pickup day that occurs on a different day of the week than its previous pickup
This data is also has text and JSON representations:
- Pickup Days:
text/plain,application/json,text/calendar (iCal) - Next Pickup:
text/plain,application/json - Next DOW Change:
text/plain,application/json
Dates are expressed as YYYY-MM-DD[ F]. The F is an optional flag (separated from the date with a single space). The only supported flag currently is Y which means a 'Yard Trimmings Collection' also occurs on that day.
The nextpickup request accepts a limit GET parameter to show the next several pickups.
(eg: /zones/vancouver-north-blue/nextpickup.txt?limit=5).
Zone Reminders
You can add and remove reminders through the API as follows.
Adding a reminder
Submit a HTTP PUT request to /zones/:zone_id/reminders containing a JSON payload with the following elements in the body:
id- A unique identifier for this reminder. Must be 3-30 characters alphanumeric.password- An optional password for this reminderemail- An email address to receive email remindersoffset- Number of hours to add to midnight of the pickup day. Defaults to -6 (eg: 6pm of the day before pickup).target- (Optional) Notification delivery target. Defaults to an email target. See below for more targets.
This will initiate creation of a reminder. Email will be sent to the email address with a confirmation link.
Reminder targets
Reminders have a target which is how the reminder should notify the user. The default target is
email:user@example.com (with the email address of the user). Here are the available reminder targets:email:email_address- Sends a regular email notification to the address.twitter:twitter_username- Sends a direct message to the twitter user. They must follow VanTrash to receive the DM.webhook:http://example.com- Sends a HTTP POST request with a JSON payload that contains details about the reminder to the URL specified. See Webhooks.org for more details.
Deleting a reminder
Submit a HTTP DELETE request to /zones/:zone_id/reminders/:id. Returns 204 on successful delete, 400 on failure.
This will send an email to confirm the reminder deletion by loading a confirmation link.
Linking to a zone
Zones can be linked to by passing the CGI parameter zone. Therefore, http://vantrash.ca/?zone=vancouver-south-blue will link to the UI with the Vancouver South Blue zone pre-clicked.
Automated Test Specification
We have developed the Vantrash API with the help of a executable test specification of how the API should perform. You can find it in our VanTrash Github Repo here.