API Documentation v2
This page outlines the operability of the spreebird.com API communications. You will find reference material on how to successfully communicate to the API with an external application.
All API calls are made via GET requests over HTTPS.
Additionally, we have API specific conditions which you must agree to or face eternal damnation (and denied API access). You are expected to not use the API in any way malicious (no law breaking, no misleading users, no manipulating read-only data, et cetera). You cannot play middle man and sell either API access or the data itself. If you cache data, it must not be stored for more than a reasonable period of time (which we have deemed as one (1) hour to ensure freshness).
spreebird.com reserves the right at any time in its sole discretion to terminate access to the API as well as make changes to these terms.
Each developer on the spreebird.com API platform will be required to obtain a developer's API key for each application they intend on producing.
To obtain a developer's key, please submit your application information at http://www.spreebird.com/api/application/new
Authentication is based solely on an application API key or the combination of the application API and user API key depending on the API method being utilized. Never should user passwords be captured or sent for validation via the API interface. Doing so will result in an immediate termination of the developer key and possibly overall restriction from using spreebird.com's services. The user API key can be found at http://www.spreebird.com/api/key
Currently the spreebird.com API is limited to 50 calls per rolling 60 seconds per combination of inbound IP address, application key, and user key (if applicable). If the rate limit has been exceeded, the system will return an HTTP status code of 503. If your application needs more than the allotted number of calls, feel free to contact us with your application key and an estimate of how many calls you need.
It's happened to all of us, a third-party API is running slow (if at all), and you're held accountable. To help avoid this situation entirely, we do encourage caching our data for short periods of time (cached data should be refreshed no less than once per hour, due to the real-time nature of our site). Caching will often times help avoid reaching the dreaded rate limit.
Every request made to the API will return one of two status codes. Each will be represented by a usable code and status message.
Responses default to JSON format, but an optional return type can be specified to change to another format. Currently, the only supported return types are XML and JSON. For XML, simply append “.xml” to the end of any API call)
Note: All API queries will produce a response.
Retrieves a list of active deals, optionally filtered by active market, local (1 for all local deals or 0 for all non-local deals for a given market) with a limit of 50 and page (defaults to 1).
Returns the deal data for a particular deal
Adds an email address to the specified CrowdSavings.com mailing list.
Retrieves a list of active markets (i.e. cities with active deals).
Logs a merchant in and returns their voucher counts.
Pings the CrowdSavings.com API to verify if it's alive.
Logs a user in and returns their voucher list, subscriptions and information.
Looks up a voucher by code or token.
Redeems a voucher by code or token.
Did you find a problem with our documentation? Are you having issues with an API call? Would you like to submit an RFE? Would you like to submit code examples to help others? Feel free to drop us an email.