Eurocodes Zoning API documentation

Article updated on17 January 2025

This document provides an overview of the Eurocodes Zoning API endpoints, including examples of requests and responses.

Setup

Obtain a Eurocodes Zoning API key

To use the Eurocodes Zoning API, you need a unique access key. You can obtain more information about the API and contact us to obtain a key from the API presentation page.

Prerequisites

You must have a Eurocodes Tools account with an organisation linked to your user account in order to configure a payment method.

Stripe subscription system

Once you have contacted an administrator, you will receive an email containing a payment link from Stripe (our payment partner) to configure a payment method in order to access the API.

API consumption is a subscription system with pay-as-you-go. To validate the subscription, you will need to enter a valid payment method (credit card or SEPA direct debit).

You will not be charged when the subscription is set up, the pay-as-you-go method will be billed to you each month and you will only be billed on your monthly consumption (by number of calls to the API). There are no additional subscription fees, so if you don’t consume anything, you don’t pay anything!

Authentification

Once you have validated your payment method, your access is automatically granted.

All API requests require authentication using an API key. Your API key will be available in your Eurocodes Tools account at the following address: https://app.eurocodes-tools.com/en/organisation-api

It is therefore essential to include your API key in the HTTP authorisation header as a Bearer Token. Omitting this key or using an incorrect format will result in a return error.

Usage

Limits

The API imposes limits on the number of requests per second, depending on your subscription package, to ensure fair use and prevent abuse. If you exceed this threshold, the API will respond with an HTTP 429 Too Many Requests status code. It is essential to manage your requests in such a way as to respect these limits to avoid any interruption in service. You can find your limit in the API response under the ecz_api_limit_rate key.

Consumption

You can track your consumption for the current billing period with each API call. The ecz_api_count key will increment as each call is made.

API version

The eurocodes_zoning_version key in the API response contains the API version used. In the event of an upgrade, we take care not to modify the existing keys so as not to break your implementations. The results themselves may change from one version to another depending on the standards, and additional keys may be added in the future.

Regenerate my API key

If necessary, you can manually regenerate your API key from your API space in the Eurocodes Tools application. Remember to enter your new key in the tools that use the API to avoid service interruption.

Endpoints

Request

Method: POST
URL : https://app.eurocodes-tools.com/api/zoning

Mandatory Parameters

There are two mandatory parameters: lat and long

lat (float)
Latitude of the point where you wish to obtain the results
long (float)
Longitude of the point where you wish to obtain the results

Note: The GPS coordinates of your point must be in a country compatible with Eurocodes Zoning.

Example (cURL)


curl --location 'https://app.eurocodes-tools.com/api/zoning' \
--header 'Content-Type: application/json' \
--header 'Bearer -YOUR_API_KEY-' \
--data '{
    "lat": 48.8566969, 
    "long": 2.3514616
}'

Example (Python)

import requests

url = "https://app.eurocodes-tools.com/api/zoning"

headers = {
    "Authorization": "Bearer <YOUR_API_KEY>"
}

payload = {
    "long": 2.3514616,
    "lat": 48.8566969
}

response = requests.post(
    url=url, 
    headers=headers, 
    json=payload
)
print(response.json())

Basic answer :

To find out more about the results, read the Explanation of the keys section.

Status Code : 200

See the API response

{
    "datas": {
        "calculateGeneralLoads": false,
        "earthquake": {
            "agR": 0.4,
            "municipality": null,
            "province": "PARIS",
            "province_id": "75",
            "standard": "<a href="https://www.legifrance.gouv.fr/affichCodeArticle.do?idArticle=LEGIARTI000030066108&cidTexte=LEGITEXT000006074220" target="_blank">Code of the Environment - Article D563-8-1 (09/01/2015)</a> + <a href="https://www.legifrance.gouv.fr/eli/arrete/2010/10/22/DEVP1015475A/jo/texte" target="_blank">JORF n°0248 of 24/10/2010 text N°5</a>",
            "zone": "1"
        },
        "eurocodes_zoning_version": "04-0717",
        "location": {
            "address": "Place de l'Hôtel-de-Ville - Esplanade de la Libération, 75004 Paris, Île-de-France",
            "altitude": 36.0,
            "altitudes_source": "European digital elevation model Copernicus 25m",
            "country": "france",
            "lat_WGS84": 48.8566969,
            "long_WGS84": 2.3514616
        },
        "snow": {
            "district": null,
            "municipality": null,
            "province": "PARIS",
            "province_id": "75",
            "sad": null,
            "sk": 0.45,
            "standard": "NF EN 1991-1-3/NA (05/2007) + A1 (07/2011)",
            "zone": "A1"
        },
        "wind": {
            "cdir_zone": null,
            "district": null,
            "municipality": null,
            "province": "PARIS",
            "province_id": "75",
            "standard": "NF EN 1991-1-4/NA (03/2008) + A1 (07/2011) + A2 (09/2012) + A3 (04/2019)",
            "vb0": 24.0,
            "zone": "2"
        }
    },
    "ecz_api_count": 15,
    "ecz_api_limit_rate": 0.1
}

Note: ecz_api_count and ecz_api_limit_rate are sent after each successful request and count the number of calls you have made in the current period and your limit rate (in requests / seconds) linked to your API subscription.

Additional parameters

Here are the additional parameters you can submit to the request:

calculate_general_loads (boolean), default = false
Calculate snow loads, wind pressures and seismic acceleration?

If calculate_general_loads is true, the following parameters are mandatory:

building_type(string)
Project use category (EN 1990 Table 2.1) to be selected from :
- “3” : For agricultural shed or similar”
- “4b” : For common structure
- “4c” : For common building with floors (apartments and/or office spaces)
- “5” : For monumental building
max_height (float), min = 0, max = 50
Maximum height (z_max) of the building in metres, used to calculate qp(z_max).
orientation(integer), min = 0, max = 90
Orientation in degrees of the sectors in relation to the North.

Example for orientation = 0°:
Sector 1 (s1) is to the north
Sector 2 (s2) to the east
Sector 3 (s3) to the south
Sector 4 (s4) to the west.

terrain_category_x(string)
The category of land in sectors 1 to 4. Varies according to the country of construction:
- Germany: [“I”, “II”, “III”, “IV”, “II-I”, “III-II”]
  Wind zones map – Germany
- Belgium: [“0”, “I”, “II”, “III”, “IV”]
  Wind zones map – Belgium
- France : [“0”, “II”, “IIIa”, “IIIb”, “IV”]
  Wind zones map – France
- France – New Caledonia : [“0”, “II”, “IIIa”, “IIIb”]
  Wind zones map – France
- Italy: [“D”, “C”, “B”, “A”]
  Wind zones map – Italy
- Luxembourg : [“0”, “I”, “II”, “III”, “IV”]
  Wind zones map – Belgium
cdir_auto (boolean), default = false
Do you automatically take into account the cdir steering coefficient?
co_complex_auto (boolean), default = false
Automatically calculate complex orography (France only)
co_marked (boolean), default = false
Automatically calculate orography?
co_manual (boolean), default = false
Manual entry of orography coefficients c_o(z) ?
co_sect1 (float), min = 1
If co_manual is true, c_o(z) of sector no.1.
co_sect2 (float), min = 1
If co_manual is true, c_o(z) of sector no. 2.
co_sect3 (float), min = 1
If co_manual is true, c_o(z)of sector no. 3.
co_sect4 (float), min = 1
If co_manual is true, c_o(z) of sector no. 4.

Example (cURL)


curl --location 'https://app.eurocodes-tools.com/api/zoning' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer -YOUR_API_KEY-' \
--header 'Cookie: session=eyJsYW5nX2NvZGUiOiJlbiJ9.Z3PG0g.RP1wefbRBcOP1nEOlNbsa6NdNSk' \
--data '{
    "long": 2.3514616,
    "lat": 48.8566969,
    "calculate_general_loads": "true",
    "building_type": "4b",
    "max_height": 20,
    "orientation": 45,
    "terrain_category_1": "0",
    "terrain_category_2": "0",
    "terrain_category_3": "0",
    "terrain_category_4": "0",
    "cdir_auto": "true",
    "co_complex_auto": "true",
    "co_marked": "true",
    "co_manual": "true",
    "co_sect1": 1,
    "co_sect2": 1,
    "co_sect3": 1,
    "co_sect4": 1,
}'

Example (Python)

import requests

url = "https://app.eurocodes-tools.com/api/zoning"

headers = {
    "Authorization": "Bearer <YOUR_API_KEY>"
}

payload = {
    "long": 2.3514616,
    "lat": 48.8566969,
    "calculate_general_loads": True,
    "building_type": "4b",
    "max_height": 20,
    "orientation": 45,
    "terrain_category_1": "0",
    "terrain_category_2": "0",
    "terrain_category_3": "0",
    "terrain_category_4": "0",
    "cdir_auto": True,
    "co_complex_auto": True,
    "co_marked": True,
    "co_manual": True,
    "co_sect1": 1,
    "co_sect2": 1,
    "co_sect3": 1,
    "co_sect4": 1,
}

response = requests.post(
    url=url, 
    headers=headers, 
    json=payload
)
print(response.json())

Response

To find out more about the results, read the Explanation of the keys section.

Status Code : 200

See the API response

{
    "datas": {
        "building": {
            "design_working_life": 50,
            "max_height": 20,
            "orientation": 45,
            "type": "4b"
        },
        "calculateGeneralLoads": true,
        "earthquake": {
            "agR": 0.4,
            "municipality": null,
            "province": "PARIS",
            "province_id": "75",
            "standard": "Code of the Environment - Article D563-8-1 (09/01/2015) + JORF n°0248 of 24/10/2010 text N°5",
            "zone": "1"
        },
        "eurocodes_zoning_version": "04-0717",
        "location": {
            "address": "Place de l'Hôtel-de-Ville - Esplanade de la Libération, 75004 Paris, Île-de-France",
            "altitude": 36.0,
            "altitudes_1000m": null,
            "altitudes_500m": null,
            "altitudes_source": "European digital elevation model Copernicus 25m",
            "country": "france",
            "lat_WGS84": 48.8566969,
            "long_WGS84": 2.3514616
        },
        "snow": {
            "design_working_life": 50,
            "district": null,
            "municipality": null,
            "province": "PARIS",
            "province_id": "75",
            "sad": null,
            "sk": 0.45,
            "sk_alt": 0.45,
            "sn": 0.45,
            "standard": "NF EN 1991-1-3/NA (05/2007) + A1 (07/2011)",
            "zone": "A1"
        },
        "wind": {
            "Iv_z": [0.121, 0.121, 0.121, 0.121],
            "K": 0.2,
            "angles_sectors": [[0, 90], [90, 180], [180, 270], [270, 0]],
            "cdir": [1.0, 1.0, 1.0, 1.0],
            "cdir_zone": null,
            "ce_z": [3.317, 3.317, 3.317, 3.317],
            "co_type": "classic",
            "co_z": [1.0, 1.0, 1.0, 1.0],
            "cprob": 1.0,
            "cr_z": [1.341, 1.341, 1.341, 1.341],
            "district": null,
            "kl": [0.162, 0.162, 0.162, 0.162],
            "kr": [1.0, 1.0, 1.0, 1.0],
            "municipality": null,
            "n_exponent": 0.5,
            "orography_alert": null,
            "orography_msg": "The effect from orography is not taken in account.",
            "p": 0.02,
            "province": "PARIS",
            "province_id": "75",
            "qp_z": [1170.4, 1170.4, 1170.4, 1170.4],
            "radius_sector": 837,
            "rho": 1.225,
            "sigmav": [3.881, 3.881, 3.881, 3.881],
            "standard": "NF EN 1991-1-4/NA (03/2008) + A1 (07/2011) + A2 (09/2012) + A3 (04/2019)",
            "terrain_categories": ["0", "0", "0", "0"],
            "vb": [24.0, 24.0, 24.0, 24.0],
            "vb0": 24.0,
            "vm_z": [32.2, 32.2, 32.2, 32.2],
            "z0": [0.005, 0.005, 0.005, 0.005],
            "z0_II": 0.05,
            "zmin": [1.0, 1.0, 1.0, 1.0],
            "zone": "2"
        }
    },
    "ecz_api_count": 14,
    "ecz_api_limit_rate": 0.1
}

Error management

All error responses include a status code and a message.

400 : Bad request

This error is returned if parameters are missing or incorrect in the request.
Example: The authorisation is not defined or a parameter is missing:

{
    "error": "Invalid API key",
    "message": "The provided API key is invalid."
}

{
    "error": "Bad Request",
    "message": "Missing Authorization in header"
}

{
    "error": "Bad Request",
    "message": "Missing mandatory parameters : lat and long"
}

If the address provided is incorrect (wrong latitude or longitude or outside the countries available in Eurocodes Zoning), you will receive this response:

{
    "error": "Invalid API key",
    "message": "No address found in the response."
}

401 : Unauthorized

If your API key is invalid or does not exist, please check your API key at https://app.eurocodes-tools.com/en/organisation-api.

{
    "error": "Unauthorized",
    "message": "Your API Key is not valid"
}

403 : Forbidden

This error occurs if your subscription is not active or if you have outstanding payments to make before you can use the API again. Please check your subscription at https://app.eurocodes-tools.com/en/organisation-api and make sure you do not have any outstanding invoices.

{
    "error": "Forbidden",
    "message": "Your subscription is not active"
}

429 : Too Many Requests

This error occurs when you reach your rate limit, the default rate limit is 0.1 request / seconds (1 request every 10 seconds) and depends on your subscription, if you wish to increase the rate limit, please contact a Eurocodes Tools administrator.

{
    "error": "Too Many Requests",
    "message": "You have reached your rate limit"
}

500 : Internal Servor Error

This error occurs when the server or the dependent API service is not currently available. This error should never occur as we guarantee up to 99% availability of the API service.

{
    "error": "Internal Server Error",
}

Explanations of the key results

Here is an example of a complete result containing all the possible keys in the answer. See below for explanations of each key.

See the API response

{
    "datas": {
        "building": {
            "design_working_life": 50,
            "max_height": 20,
            "orientation": 45,
            "type": "4b"
        },
        "calculateGeneralLoads": true,
        "earthquake": {
            "agR": 0.4,
            "municipality": null,
            "province": "PARIS",
            "province_id": "75",
            "standard": "Code of the Environment - Article D563-8-1 (09/01/2015) + JORF n°0248 of 24/10/2010 text N°5",
            "zone": "1"
        },
        "eurocodes_zoning_version": "04-0717",
        "location": {
            "address": "Place de l'Hôtel-de-Ville - Esplanade de la Libération, 75004 Paris, Île-de-France",
            "altitude": 36.0,
            "altitudes_1000m": null,
            "altitudes_500m": null,
            "altitudes_source": "European digital elevation model Copernicus 25m",
            "country": "france",
            "lat_WGS84": 48.8566969,
            "long_WGS84": 2.3514616
        },
        "snow": {
            "design_working_life": 50,
            "district": null,
            "municipality": null,
            "province": "PARIS",
            "province_id": "75",
            "sad": null,
            "sk": 0.45,
            "sk_alt": 0.45,
            "sn": 0.45,
            "standard": "NF EN 1991-1-3/NA (05/2007) + A1 (07/2011)",
            "zone": "A1"
        },
        "wind": {
            "Iv_z": [0.121, 0.121, 0.121, 0.121],
            "K": 0.2,
            "angles_sectors": [[0, 90], [90, 180], [180, 270], [270, 0]],
            "cdir": [1.0, 1.0, 1.0, 1.0],
            "cdir_zone": null,
            "ce_z": [3.317, 3.317, 3.317, 3.317],
            "co_type": "classic",
            "co_z": [1.0, 1.0, 1.0, 1.0],
            "cprob": 1.0,
            "cr_z": [1.341, 1.341, 1.341, 1.341],
            "district": null,
            "kl": [0.162, 0.162, 0.162, 0.162],
            "kr": [1.0, 1.0, 1.0, 1.0],
            "municipality": null,
            "n_exponent": 0.5,
            "orography_alert": null,
            "orography_msg": "The effect from orography is not taken in account.",
            "p": 0.02,
            "province": "PARIS",
            "province_id": "75",
            "qp_z": [1170.4, 1170.4, 1170.4, 1170.4],
            "radius_sector": 837,
            "rho": 1.225,
            "sigmav": [3.881, 3.881, 3.881, 3.881],
            "standard": "NF EN 1991-1-4/NA (03/2008) + A1 (07/2011) + A2 (09/2012) + A3 (04/2019)",
            "terrain_categories": ["0", "0", "0", "0"],
            "vb": [24.0, 24.0, 24.0, 24.0],
            "vb0": 24.0,
            "vm_z": [32.2, 32.2, 32.2, 32.2],
            "z0": [0.005, 0.005, 0.005, 0.005],
            "z0_II": 0.05,
            "zmin": [1.0, 1.0, 1.0, 1.0],
            "zone": "2"
        }
    },
    "ecz_api_count": 14,
    "ecz_api_limit_rate": 0.1
}

General:

These keys are located at the root of the API response.

ecz_api_count (int)
The number of API calls for the current billing period
ecz_api_limit_rate (float)
Your call limit
eurocodes_zoning_version (string)
Eurocodes Zoning software version
calculateGeneralLoads (boolean)
Calculation of active and inactive expenses.

Building :

design_working_life (int)
Design life in years (EN 1990 Table 2.1)
max_height (float)
Maximum height in metres
orientation (int)
Orientation of sectors from the North in degrees
type (string)
Project use category (EN 1990 Table 2.1)

Earthquake :

Results for the earthquake.

agR (float)
Maximum reference acceleration in m/s² for class A soil
municipality (string)
province (string)
province_id (string)
standard (string)
zone (string)
Seismic zone

Location :

address (string)
Indicative address corresponding to the details below
altitude (float)
Altitude in metres in line with the building (coordinates below)
altitudes_1000m (Array[int] | null)
Altitudes in metres within a radius of 1000m. EN 1991-1-4/NA (FR) Clause 4.3.3 (1) – Procedure 1 with [N, NE, E, SE, S, SO, W, NO].
altitudes_500m (Array[int] | null)
Altitudes in metres within a radius of 500m. EN 1991-1-4/NA (FR) Clause 4.3.3 (1) – Procedure 1 with [N, NE, E, SE, S, SO, W, NO].
altitudes_source (string)
country (string)
lat_WGS84 (float)
long_WGS84 (float)

Snow :

Results for snow.

design_working_life (int)
Calculation life in years
district (string)
municipality (string | null)
province (string)
province_id (string)
sad (float)
Accidental snow load sad in kN/m². according to the conditions defined in the relevant national annex (optional)
sk (float)
Characteristic snow load sk,0 in kN/m² at an altitude of 0 m.
sk_alt (float)
Characteristic snow load in kN/m², taking altitude into account.
sn (float)
Snow load on the ground in kN/m², taking into account altitude and corresponding to the return period concerned.
standard (string)
zone (string)
Snow zone

Wind :

Results for wind. Lists of 4 values correspond to [sector 1, sector 2, sector 3, sector 4].

Iv_z (Array[float])
Turbulence intensities. EN 1991-1-4 §4.4
K (float)
Shape parameter.
angles_sectors (Array[Array[int])
Definition of sectors in degrees.
cdir (Array[float])
Direction coefficients c_dir.
cdir_zone (string)
Field for calculating direction coefficients.
ce_z (Array[float])
Exposure coefficients c_e(z).
co_direction_list (Array[str])
Wind exposure (upwind / downwind) with [sector 1, sector 2, sector 3, sector 4].
co_s_factors (Array[float])
With [sector 1, sector 2, sector 3, sector 4].
co_type (string)
Type of orography.
co_z (Array[float])
Coefficients of orography c_o(z).
cprob (float)
Probability coefficient c_prob. EN 1991-1-4 §4.2.
cr_z (Array[float])
Roughness coefficients c_r(z).
distance_to_crest (object)
Distance to crest in metres.
Example: {‘line1’: {‘distance_to_crest1’: 39, ‘distance_to_crest2’: 0}, ‘line2’: {‘distance_to_crest1’: 0, ‘distance_to_crest2’: 117}}
district (string)
kl (Array[float])
Turbulence coefficients.
kr (Array[float])
Factors on the ground
line1_obstacleH1 (int | null)
Obstacle height in metres for wind from sector 1
line1_obstacleH2 (int | null)
Obstacle height in metres for wind from sector 3
line1_terrain_slope_1 (float | null)
Horizontal length of slope in metres for wind from sector 1
line1_terrain_slope_2 (float | null)
Slope for a sector 3 wind
line1_terrain_slope_L1 (int | null)
Horizontal length of slope in metres for wind from sector 1
line1_terrain_slope_L2 (int | null)
Horizontal length of slope in metres for wind from sector 3
line2_obstacleH1 (int | null)
Height of obstacle in metres for a wind from sector 2
line2_obstacleH2 (int | null)
Height of obstacle in metres for a wind from sector 4
line2_terrain_slope_1 (float | null)
Slope for a sector 2 wind
line2_terrain_slope_2 (float | null)
Slope for a sector 4 wind
line2_terrain_slope_L1 (int | null)
Horizontal length of slope in metres for wind from sector 2
line2_terrain_slope_L2 (int | null)
Horizontal length of slope in metres for wind from sector 4
municipality (string | null)
n_exponent (float)
Exhibitor n. EN 1991-1-4 §4.2.
obstacle_type_list (Array[str])
Type of obstacle (hill / hills / escarpments / flat) – with [sector 1, sector 2, sector 3, sector 4].

Cliff or escarpment

Isolated hill or chain of hills
(Chained hills are assumed to have a long length perpendicular to the wind, equal to at least 10 times the height H of the orographic obstacle. Isolated hills, on the other hand, have a limited length compared to their height, so that the wind can go around them laterally, and not just vertically; in this case, the overspeed is less when crossing the ridge).

orography_alert (string | null)
Alert if complex orography cannot be applied in France.
orography_msg (string)
p (float)
Annual probability of exceedance. EN 1991-1-4 §4.2.
province (string)
province_id (string)
qp_z (Array[float])
Peak dynamic pressure q_p(z) in N/m². EN 1991-1-4 §4.5.
radius_sector (int)
Radius of angular sectors in metres.
rho (float)
Air density in kg/m3. EN 1991-1-4 §4.5.
sigmav (Array[float])
Standard deviations of turbulence σ_v.
standard (string)
terrain_categories (Array[string])
vb (Array[float])
Reference wind speed v_b in m/s.
vb0 (float)
Base value v_b0 in m/s.
vm_z (Array[float])
Average wind speed v_m(z) in m/s.
z0 (Array[float])
Roughness length z₀ in metres.
z0_II (float)
Reference roughness length z_0,II in metres.
zmin (Array[float])
Minimum height z_min in metres.
zone (string)
Wind zone

Help

This documentation provides the information you need to interact with the API. For further assistance, please contact the helpdesk.