Skip to content

API Limits

Limits are an essential part of ensuring that our API functions correctly. The following sections explain these limits and describe factors that affect API performance and capability.

A summary of limits is as follows.

Service Limit
Portfolio & synchronous Max layers = 40 per call
Portfolio Max locations = 10m per call
Synchronous Max processing units = 250 per call
Portfolio & synchronous Rate limit = 50 calls per 10 seconds (with 1 minute timeout if exceeded)
Portfolio (annual data license only) Max monthly processing units = customer specific
Portfolio and synchronous Data egress limit = 1 TB per month

Terminology

Synchronous call: A call made to our point or polygon or statistic endpoints. Response time is in the order of individual seconds.

Portfolio call: A call made to our portfolio endpoint. The status of the request can be polled and once complete the output file can be downloaded. Compute time can be up to several hours. If necessary portfolio requests will be queued which will extend the overall time to completion.

Static layer: A data value which can be returned directly via the API without the need for further calculations. ‘Current’ flood map data and terrain data are examples of static layers.

Dynamic layer: A data value that needs interim calculations to take place before being returned via the API. Climate options in our Global Flood Map data are an example of dynamic layers.

Processing units are a proxy for the complexity of processing required to generate dynamic layers.

Number of layers limit

This applies to both synchronous and portfolio calls.

The maximum number of layers (dynamic or static) in any API call is 40.

The API will return an error code if an API call is made that exceeds this limit.

Number of locations limit

This applies to portfolio calls only.

A location is specified by a latitude / longitude pair and constitutes one row in the portfolio input csv.

The maximum number of locations is 10,000,000.

The API will return an error code if an API call is made that exceeds this limit.

Rate Limit

This applies to portfolio and synchronous calls.

The maximum amount of API calls is limited to 50 per 10 seconds.

The API will return an error code and block further API calls for 1 minute if this limit is exceeded.

Data egress limit

This applies to synchronous and portfolio calls.

A ‘fair use’ egress limit of 1 TB per month applies to all customers.

Processing units limits

Processing units are a proxy for the compute resource required for a given API call. The higher the number of processing units the longer an API call will take to return data.

Processing units are calculated by:

  1. Calculating a layer weight for each layer in a given API call. See below for details.
  2. Summing the layer weights in a call
  3. Multiplying the sum of layer weights by the number of locations or total area (in km^2) in the call.

A layer weight is defined as:

  • Static layer = 1
  • Dynamic inland layer = 2
  • Dynamic coastal layer = 4
  • Non-standard return period x 2 (with a minimum total layer weight of 4)

Static layers are defined here. Dynamic layers are defined here.

  • Inland layers are those with Layer ID Type = PLUVIAL or FLUVIAL
  • Coastal layers are those with Layer ID Type = COASTAL
  • Standard return periods are: 5, 10, 20, 50, 100, 200, 500, 1000

For example:

  • A dynamic coastal layer has a layer weight of 4
  • A dynamic coastal layer with a non-standard return period has a layer weight of 4 x 2 = 8
  • The processing units in an API call with 10 dynamic coastal layers (each with layer weight = 4) and 5 points are 10 x 4 x 5 = 200

The maximum number of processing units for a synchronous API call is 250.

The maximum number of processing units for portfolio API calls is limited per month and is customer specific.