API Limits

Calls to the Empire Avenue API are both IP and User Rate Limited.

IP and User Limits

Most API calls for the Empire Avenue API require authentication as a specific user. In other words you will be performing the calls on behalf of another user whose username (TICKER) and password has been given to your application. Most API calls are there for User Rate Limited. There are other calls which may not require any user authentication (public queries) and these will be limited by IP Rate Limits if there is no user attached. So to be very clear:

1. Connect to Empire Avenue API with user credentials and running a query as Bob, Bob's User Rate Limits will apply (150/hour). Once the limit is reached, Bob cannot run queries with any application. Since each application returns the type of rate limits, reset time and the available requests, your application should make sure not to block Bob's use from other applications

2. Connecting to Empire Avenue API without user credentials and running a public query will deplete your IP Rate limits (150/hour). Failed calls to authenticate may count against your IP, so be warned.

User Rate Limits will always take precedence over IP Rate Limits

IP Rate: 150/hour User Rate: 150/hour

If you are going to be calling the API on the user's behalf, make sure that you are calling with the user's credentials otherwise your IP could be limited.

Almost every call requested from the API will contain information on how much your rate has been used and when the limit will reset. The data is contained in the "meta" data returned by every call

//The following is an example of data returned with every call "meta": { "requested_user": (string) ticker "total_rows": (int) rows, this will be the max returned in a call with multiple pages "requested_page": (int) requested page of data "next_page": (int) next page of data "total_pages": (int) previous page of data "uri": (string) URI "limit": (int) Maximum Limit For This Call "limit_type": (string) Either "user" or "ip" "requests": (int) Requests made since last Limit Reset "reset": (int) Number of seconds to next Reset "recorded": (string) Datetime stamp in GMT for this call }

Failed Attempts

Make sure that your application takes into account failed attempts for logins. Your application will be automatically blocked from using the API server if you try to call the API with invalid credentials too often. For example, if you have 5 failed attempts on a user's account then your application will be blocked for an hour from that user's account. If you have excessive failed attempts on multiple users accounts then your application could be blocked from Empire Avenue completely.

We suggest that on two subsequent failed attempts that you stop querying that user's account in case you get blocked by Empire Avenue. See the messages for all the different errors.