National Deals

API Documentation v2

Introduction

This page outlines the operability of the crowdsavings.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.



Terms of Use

By using our API in any capacity, you are agreeing that you and your application will comply with our Terms of Use and Privacy Policy.

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).

crowdsavings.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.



Requirements

Each developer on the crowdsavings.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.crowdsavings.com/api/application/new

Authentication

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 crowdsavings.com's services. The user API key can be found at http://www.crowdsavings.com/api/key

Rate Limiting

Currently the crowdsavings.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.



Caching Policy

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.



Responses

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.



Methods

deal/active
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).

deal/fetch
Returns the deal data for a particular deal

email/subscribe
Adds an email address to the specified CrowdSavings.com mailing list.

market/active
Retrieves a list of active markets (i.e. cities with active deals).

merchant/login
Logs a merchant in and returns their voucher counts.

system/ping
Pings the CrowdSavings.com API to verify if it's alive.

user/login
Logs a user in and returns their voucher list, subscriptions and information.

voucher/lookup
Looks up a voucher by code or token.

voucher/redeem
Redeems a voucher by code or token.



Libraries

PHP



Contact

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.