Limitations

Cardinality Limits

The API enforces a cardinality limit of 1.5 million for data queries to ensure optimal performance and response times.

Concept & Formula

Cardinality is calculated as the product of all unique filter value combinations in your query. It represents the maximum potential number of data records that could be returned.

Formula:

Cardinality = count(filter_1) × count(filter_2) × ... × count(filter_n)

Implicit Filters

When you omit a filter from your query, the API automatically includes ALL values for that filter from your data collection's granularity. This can significantly increase your query's cardinality, even if you're not explicitly requesting those values.

Implicit Example

Consider a data collection with the following granularity:

location_id: [1, 2, 3, 4, 5]                        # 5 locations
age_group_id: [1, 2, 3, 4, 5, 6]                    # 6 age groups
gender_id: [1, 2, 3]                                # 3 genders
cause_id: [1, 2, 3, 4]                              # 4 causes
metric_id: [1]                                      # 1 metric
measure_id: [1]                                     # 1 measure
year: [2018, 2019, 2020, 2021, 2022, 2023, 2024]    # 7 years

Client query:

{
    'location_id': '1,2',    # 2 locations specified
    'gender_id': '1'         # 1 gender specified
}

Cardinality calculation:

count(location_id) × count(age_group_id) × count(gender_id) × count(cause_id) × count(metric_id) × count(measure_id) × count(year)
= 2 × 6 × 1 × 4 × 1 × 1 × 7
= 336

Even though the query only specifies 2 filters explicitly, the cardinality includes all values from the omitted filters (age_group_id, cause_id, metric_id, measure_id, and year).

Explicit Example

For a query with all filters explicitly defined:

{
    'location_id': '1,2,3,4,5',         # 5 locations
    'age_group_id': '1,2,3,4,5,6',      # 6 age groups
    'gender_id': '1,2,3',               # 3 genders
    'cause_id': '1,2,3,4',              # 4 causes
    'measure_id': '1',                  # 1 measure
    'metric_id': '1',                   # 1 metric
    'year': '2025'                      # 1 year
}

Cardinality calculation:

5 × 6 × 3 × 4 × 1 × 1 × 1 = 360

Since 360 < 1,500,000, this query is allowed.

Error Handling

If your query exceeds the 1.5 million cardinality limit, the API will return an error. To resolve this:

1. Explicitly specify all filters to avoid unintentionally including all values

2. Split your query into multiple smaller requests

3. Reduce the number of filter values by requesting data in batches

4. Check the data collection granularity to understand which filters have many values

Rate Limits

The service is designed for high-volume traffic and scales horizontally based on demand. We do not impose fixed, published rate limits on requests per second, per day, or total quotas for legitimate use.

However, for operational stability and to prevent abuse, the service employs dynamic throttling and concurrency limits. If a client exceeds acceptable usage patterns (e.g., thousands of requests per second from a single IP or an excessively high number of concurrent connections), requests may be temporarily throttled or rejected with a specific HTTP status code, such as 429 Too Many Requests.

Best Practices

• Always specify all relevant filters explicitly to control cardinality and avoid unexpectedly large queries

• Calculate the expected cardinality before making large data requests, accounting for implicit filter values

• Use the granularity endpoints to understand the full set of available filter values in your data collection

• When working with large datasets, prefer multiple smaller requests with explicit filters over single large requests

• Implement proper error handling to manage cardinality limit exceptions