Sending yourself notifications using the Boxcar API

Introduction

The Boxcar user API is a standard REST API over HTTPS, with JSON responses. All API calls have a base URL of https://boxcar.io. It's really that simple. In order to access the API, you must first purchase the Growl service. Currently, only the ability to push notifications to yourself is generally available. If you have a special request, please don't hesitate to e-mail us: support@boxcar.io.

Authentication

Authentication is managed using HTTP authentication ("Basic"), consisting of your email address and password.

Responses

All responses are returned using standard JSON arrays or hashes with an HTTP status code of 200 if the request succeeds.

For request failures, you will receive either HTTP status 401 or 400. If you receive an HTTP status code of 400, it is because you failed to send the proper parameters. For HTTP status code 401's, it is because the user does not have the Growl service added.

Rate limiting

Currently there is no rate limiting in place. However, for iPhone devices, we have seen push notifications become significantly delayed or not delivered at all, if multiple notifications are sent per second to one device. Please do not abuse Boxcar or your services will be cancelled.

Sample Code

Ruby - http://github.com/boxcar/boxcar_api
Python - http://github.com/AggroBoy/push.py

Notification API Calls

Notifications are what Boxcar is all about. Using the Growl service, you can setup your own custom redirections that match the 'from_screen_name' parameter below.

Creating Notifications

POST /notifications

The parameters are:

• notification[from_screen_name] — The user or application sending the notification. This is matched for the redirect performed by Boxcar (if set by the user). This is a required field.
• notification[message] — The message to display to the user. This message should be at a maximum somewhere around 140 characters in length. Longer messages will be truncated depending on the client receiving it. This is a required field.
• notification[from_remote_service_id] — An integer value that will uniquely identify the notification, and prevent duplicate notifications about the same event from being created. This is an optional field, but it is strongly recommended that you use it.
• callback — An optional parameter used for JSONP responses.

Retrieving Notifications

GET /notifications

Returns the latest 20 notifications for the user. This URL will also take a parameter of ?page followed by the integer page number. The first result is always a simple hash consisting of the total number of notifications available for the user.