Eurocodes Zoning API documentation

Article updated on6 February 2025

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

Setup

You can find general information about our API on the 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.

Obtain a Eurocodes Zoning API key

Once you have created your account, you can go to https://app.eurocodes-tools.com/en/organisation-api and choose a subscription package. You will be redirected to a payment page managed by Stripe (our payment partner) to pay for your subscription (by credit card or SEPA direct debit).

You will be invoiced when the subscription is set up and your subscription will be automatically renewed each month. You can cancel it at any time (in which case you will have access until the end of the current period).

Once you have validated your subscription, you will be redirected to the API management page. Your API access key and invoice will be available on the API page of your organisation panel. Your key is automatically activated and ready for use. Your consumption is displayed on this page and in the response when you call the API.

Authentication

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 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 in order to avoid any interruption in service. You can find your limitation in the API response under the key ecz_api_limit_rate

Consumption

You can track your consumption for the current billing period during each API call. The ecz_api_count_left key will decrement as each call is made. The out_of_plan key will default to false and will change to true if you exceed the number of calls specified in your subscription.

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_left": 998,
    "ecz_api_limit_rate": 0.1,
    "out_of_plan": false
}

Note: ecz_api_count_left, ecz_api_limit_rate and out_of_plan are sent after each successful request and are respectively :

The number of calls to the left that you can make in the pending period linked to your API subscription (before being ‘Out of Plan’), this will be reduced by one for each successful request.
The maximum API throughput limit (in number of requests per second)
A Boolean indicating whether you are Out Of Plan (if True, your ecz_api_count_left must be less than 0).

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_left": 998,
    "ecz_api_limit_rate": 0.1,
    "out_of_plan": false
}

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": "Bad Request",
    "message": "Missing API Key in Authorization header"
}

{
    "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": "Bad Request",
    "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_left": 998,
    "ecz_api_limit_rate": 0.1,
    "out_of_plan": false
}

General:

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

ecz_api_count_left (int)
The number of calls remaining in your subscription for the current billing period.
out_of_plan (bool)
Have you exceeded the number of calls in your subscription?
ecz_api_limit_rate (float)
Your call limit by seconds
eurocodes_zoning_version (string)
Eurocodes Zoning software version
calculateGeneralLoads (boolean)
Calculate the general loads ?

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.