DERA API Reference

Authentication

Authenticated endpoints use JWT bearer tokens. Obtain a token via /auth/login and include it in the Authorization header of subsequent requests. Tokens expire after 120 minutes.

Interactive docs (Swagger UI): dera.earth/DeraAPI/swagger

Create a new account. Returns the created user object.

Request Body (JSON)

POST /auth/register
Content-Type: application/json

{ "email": "you@example.com", "password": "yourpassword" }

Returns a JWT bearer token. Store it and include it as Authorization: Bearer <token> on authenticated requests.

Request Body (JSON)

// Response
{ "accessToken": "eyJ...", "token_type": "bearer" }

Returns the currently authenticated user's profile. Requires a valid bearer token.

GET /auth/me
Authorization: Bearer eyJ...

// Response
{ "id": 1, "email": "you@example.com", "username": "you",
  "is_active": true, "is_email_verified": false,
  "created_at": "2026-01-01T00:00:00", "last_login_at": "2026-05-03T10:00:00" }

Returns environmental risk scores for a coordinate pair. The engine analyzes hundreds of land uses within a configurable radius and produces weighted scores across 5 categories. Requires a valid JWT bearer token.

Query Parameters

Example Request

GET https://www.dera.earth/DeraAPI/DeraApi/active
    ?lon=34.7818
    &lat=32.0853
    &CalcType=All
Authorization: Bearer eyJ...

Response

Returns a semicolon-delimited string (not JSON). See Response Format for parsing details.

Noise:6.443;Soil:10;Radiation:10;Air Quality:6.853;Ecology:1.15;Address:Israel, Tel Aviv

AI chat intent detection. Accepts a user message along with the current app context and returns a conversational reply plus a structured intent token that drives UI actions.

Request Body

{
  "message": "What does a score of 6 mean for air quality?",
  "context": {
    "stage": "results_ready",
    "hasLocation": true,
    "hasResults": true,
    "address": "Tel Aviv, Israel",
    "scores": {
      "Noise": 6.443,
      "Soil": 10,
      "Radiation": 10,
      "Air Quality": 6.853,
      "Ecology": 1.15
    }
  }
}

Context Stage Values

Response

{
  "reply": "A score of 6.85 for Air Quality indicates moderate air quality...",
  "intent": "general"
}

Intent Values

AI narrative analysis of computed scores. Forwards to the PyController service and returns a human-readable interpretation of the environmental assessment.

Request Body

{
  "lastResults": {
    "Noise": 6.443,
    "Soil": 10,
    "Radiation": 10,
    "Air Quality": 6.853,
    "Ecology": 1.15,
    "Address": "Tel Aviv, Israel"
  },
  "context": {
    "address": "Tel Aviv, Israel",
    "lng": 34.7818,
    "lat": 32.0853
  }
}

Response

{
  "text": "This location shows excellent soil and radiation scores (both 10/10), indicating low contamination risk and no significant electromagnetic sources nearby. Air quality scores moderately at 6.85, reflecting urban transport activity in the area. Ecology is the weakest dimension at 1.15, suggesting limited green space in proximity..."
}

Generates a full PDF report and returns it as a Base64-encoded string. Accepts all parameters from the Score Analysis endpoint plus the additional parameters below.

Additional Parameters

Example Request

GET https://www.dera.earth/ExtractOSMMapProd/ExtractOSMMap/byCoordinate
    ?lon=34.7818
    &lat=32.0853
    &Scale=1000
    &generateBase64Report=true
    &CustomerName=Jane%20Smith
    &Recipients=jane%40example.com
    &ProjectName=Main%20St%20Appraisal
    &Lang=EN_us

Response

Returns a Base64-encoded PDF string.

JVBERi0xLjQKJ... (Base64-encoded PDF)

Excel Integration

No development resources? Working with a large address list? DERA provides a ready-made Microsoft Excel workbook that connects directly to the API using Power Query — no coding required. Paste your addresses into column A, refresh the query, and all five environmental scores populate automatically across your entire list.

Requirements

• Microsoft Excel 2016 or later
• A valid DERA API token — sign in above to get yours
• Macros must be enabled: when prompted by Excel, click Enable Editing, then Enable Content

How to Use

1. Open the downloaded API_Sample.xlsx file in Microsoft Excel.
2. When Excel shows the security bar at the top, click Enable Editing and then Enable Content — macros must be active for the query to run.
3. Enter or paste your addresses into column A, one address per row.
4. Go to the Data tab on the ribbon, then click Queries & Connections. A sidebar will open on the right side.
5. In the sidebar you will see the Dera query. Right-click it and select Refresh.
6. The API will process each address in your list and fill in the Noise, Soil, Radiation, Air Quality, and Ecology scores alongside the geocoded address string.

Response Format

The Score Analysis endpoint returns a semicolon-delimited string, not JSON. Split on ; then on : to parse:

// JavaScript
const raw = "Noise:6.443;Soil:10;Radiation:10;Air Quality:6.853;Ecology:1.15;Address:Israel, Tel Aviv";
const result = {};
raw.split(";").forEach(part => {
  const colonIdx = part.indexOf(":");
  const key = part.slice(0, colonIdx).trim();
  const val = part.slice(colonIdx + 1).trim();
  result[key] = val;
});
// result → {
//   Noise: "6.443",
//   Soil: "10",
//   Radiation: "10",
//   "Air Quality": "6.853",
//   Ecology: "1.15",
//   Address: "Israel, Tel Aviv"
// }

Note: Address may contain colons (e.g. city names with suffixes), so split only on the first colon per segment.

Score Scale

10 = best (lowest environmental risk). 0 = worst.

The overall DERA Index is a weighted average of all five category scores. Air Quality and Noise each carry double weight (×2), while Soil, Radiation, and Ecology carry single weight (×1):

Overall = (AirQuality×2 + Noise×2 + Soil×1 + Radiation×1 + Ecology×1) / 7

Score Categories

Every response includes the following fields: