Source: https://eventregistry.org/documentation?tab=introduction # API Documentation This is the documentation page intended to demonstrate various API endpoints that you can use and the parameters that are available when calling them. Different API endpoints are grouped by topic in the left side menu. For most endpoints you can also check multiple code examples that demonstrate it's use using your preferred programming language. ## Registration and authorization In order to make the API requests you will need to provide an API key. To obtain an API key you have to **[create an account](/register)** (registration is free and it gives you 2.000 [tokens](/tokens) total for testing purposes). Once you activate your account and login, you will be able to find you API key on your [settings page](/settings?tab=settings). When making REST API requests, your API key has to be provided as a parameter in the url (e.g. `apiKey=YOUR_API_KEY`). In order to use more than 2.000 tokens you will have to subscribe to a [paid plan](/plans). ## Response codes Event Registry uses conventional HTTP response codes to indicate the success or failure of an API request. In general: Codes in the 2xx range indicate success. Codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter is missing, all tokens on the plan were already used, etc.). Codes in the 5xx range indicate an error with Event Registry's servers (very rare). | HTTP status codes | | | --- | --- | | **200** | **Success.** Everything worked as expected. | | **204** | **Information not available.** Request succeeded, but the requested information is not available. | | **400** | **Bad request.** The request was unacceptable, most likely due to invalid or missing parameter. | | **401** | **User's limit reached.** The user reached the limit of the tokens in his account. The requests are rejected. | | **429** | **Too many requests.** The user is making too many simultaneous requests. The requests are rejected. Check the Rate Limiting section below to prevent such cases. | | **403** | **Forbidden.** The user's IP or account is disabled, or if all the tokens have been used. Check the error message for more details. | | **500** | **Internal error.** Internal error occured while processing the request. | | **503** | **Service unavailable.** The service is currently not available. | ## Rate limiting Event Registry has rate limits in place to ensure that the service is available to all users. The rate limits are based on the number of simultaneous requests that the user is making at the same time. The maximum allowed number of simultaneous requests that the user can be executing at the same time is 5. If more requests are made, the user will receive a 429 status code in the response and the request will not be executed. The suggested approach is to not even make the code parallel but instead make requests sequentially, one after the other. ## Limits on the conditions in the query When making queries, you can specify multiple conditions, like keywords, concepts, categories, source, locations, etc. In some cases you need to provide multiple conditions of the same type, like multiple keywords. For each type of the condition, there is a maximum number of items that you can provide in a single query. The limits are set differently for trial users vs. users with a paid API subscription and are shown in the table below. | | Trial | Paid subscribers | | --- | --- | --- | | **Sources** | 1,000 | 50,000 | | **Keywords** | 15 | 60 | | **Concepts** | 15 | 60 | | **Categories** | 10 | 20 | | **Languages** | 5 | 10 | | **Locations** | 10 | 15 | ## Token usage for API calls Each API request consumes a number of tokens from your account. Different types of requests cost a different number of tokens. Two things determine the price of a request: - **The type of data** you request (searching articles, searching events, computing an aggregate, or analyzing text). - **The time period** you query. Accessing only recent data (the last 30 days) has a fixed, low cost. Accessing the archive (data since 2014) is charged per each year of data that the query covers. When analyzing your own text with the text analytics endpoints (sentiment, categorization, entity extraction, etc.), tokens are charged per analyzed document. These costs are well below one token per document, so a single token covers the analysis of many documents. **Searching and aggregating data** | Request type | Recent data (last 30 days) | Archive data (since 2014) | | --- | --- | --- | | **Search articles** | 1 token | 5 tokens / searched year | | **Search events** | 5 tokens | 20 tokens / searched year | | **Simple aggregates** top concepts, tag cloud, locations, timeline, sources, sentiment, concept graph, categories | 5 tokens | 10 tokens / searched year | | **Complex aggregates** concept trends, date mentions, event clustering, similar events | 10 tokens | 50 tokens / searched year | **Text analytics endpoints** | Endpoint | Cost per document | | --- | --- | | **Language detection** | 0.01 tokens | | **Named entity detection** | 0.02 tokens | | **Sentiment detection** | 0.02 tokens | | **Semantic annotation** | 0.04 tokens | | **Text categorization** | 0.04 tokens | | **Semantic text similarity** | 0.05 tokens | | **Extract article info** | 0.05 tokens | For the full, up-to-date breakdown of token costs and the number of tokens included in each plan, see the [plans page](/plans) and the [tokens page](/tokens). ## Python SDK, Node.js SDK In order to make data access as easy as possible we have build [Python](https://github.com/EventRegistry/event-registry-python) and [Node.js](https://github.com/EventRegistry/event-registry-node-js) SDK libraries, which are accessible on our Github pages. You can check their corresponding documentation pages ([Python](https://github.com/EventRegistry/event-registry-python/wiki), [Node.js](https://github.com/EventRegistry/event-registry-node-js/wiki)) for an introduction on how to use them. ## OpenAPI specification You can also find the whole API specification in the YAML file linked below. **[Download YAML file](https://eventregistry.org/static/api.yaml)**.