Frequently asked questions

Our API provides seamless access to our data, enabling you to integrate it into your applications for compliance checks, research, or other purposes.

API Usage Limits and Quotas

API keys have a default limit of how many requests per month a key can perform. These limits (quotas) are set to avoid abuse of the service and unexpected cost overruns. If you exceed the allocated quota in a given calendar month, requests will be rejected with a 429 HTTP status code until the beginning of the next month.

Of course, we're more than happy to increase a quota: the quota is meant as a safety stop, not a limitation. Contact our support team and indicate what limit you would like to see applied to the key (if any).

• Standard Quota: Our default API plan includes a set number of calls per month, suitable for moderate usage.
• Custom Quota: If you require a higher volume of API calls, we offer custom plans to accommodate your needs. Please contact us to discuss your requirements.

To check your current API key quota and usage:

1. Access Your Account Dashboard: Log in to your account on our website.
2. View API Usage: Navigate to the API usage section to see your total quota, the number of calls used, and your remaining balance.

If you find that you're consistently exceeding your quota, consider upgrading your plan or optimizing your API calls to reduce unnecessary requests.

Uses of the API That Are Metered and Cost Money

All API endpoints that retrieve data are metered and count towards your quota. This includes:

• Search Endpoints: Using the /search endpoint to query entities based on names or other attributes.
• Match Endpoints: Utilizing the /match endpoint for entity matching against your own data.
• Entity Retrieval: Accessing detailed entity information via the /entities/{entity_id} endpoint.

The /match API counts the number of logical queries you've conducted: if you submit a batch of 10 query entities to be screened, that HTTP request will be counted as 10 queries. Any request which returns an error (indicated by a non-200 HTTP response code) is not counted.

The self-hosted API does not use metering, you only need a bulk data license to have the right to use the data.

Optimizing Your API Calls

To make efficient use of your API quota and reduce costs, consider the following strategies:

1. Batch Requests: Utilize batch endpoints where available to process multiple queries in a single API call.
2. Caching Results: Implement caching in your application to store frequently accessed data, reducing the need for repeated API calls.
3. Efficient Querying: Refine your search queries to retrieve only the necessary data. Use filters and parameters to limit the scope of your requests.
4. Error Handling: Ensure your application correctly handles errors and retries only when appropriate. Avoid loops that may cause excessive calls due to unhandled exceptions.
5. Monitor Usage: Regularly monitor your API usage through your account dashboard to identify unusual patterns or spikes in requests.

If you suspect that you're making more API calls than necessary, it may be due to issues in your programming. Review your application's logic to ensure that API calls are made intentionally and efficiently. We're available to assist you in optimizing your integration—feel free to contact our support team for guidance.

Identifying and Resolving Excessive API Calls

If you notice that your application is making more API calls than expected:

• Audit Your Code: Review your application's logic to identify any loops or recursive calls that may be generating unnecessary requests.
• Implement Logging: Use logging to track API call patterns and pinpoint where excessive calls may be occurring.
• Use Throttling Mechanisms: Implement rate limiting on your end to prevent your application from exceeding desired call frequencies.

We're here to help. If you need assistance in diagnosing or resolving issues related to API call volumes, please reach out to our support team.

For further assistance, please refer to our API documentation, or contact our support team at support@opensanctions.org.