POST /api/v1/analyze — Spatial Analysis JSON Response

The /analyze endpoint accepts a GeoJSON Feature with a Polygon or MultiPolygon geometry, validates it, runs the full spatial analysis against all 7 environmental layers stored in PostGIS, and returns the results as JSON. It is primarily used by the frontend to preview layer intersections on the map before the user decides to generate a PDF report. Method and path: POST /api/v1/analyze

Request

Content-Type: application/json The request body must be a GeoJSON Feature object with a valid polygon geometry in EPSG:4326 (WGS84 longitude/latitude).

Parameters

type

string

required

Must be "Feature".

geometry

object

required

GeoJSON geometry object describing the parcel boundary.

Show geometry fields

geometry.type

string

required

Must be "Polygon" or "MultiPolygon". All other geometry types are rejected.

geometry.coordinates

array

required

Coordinate ring array in EPSG:4326 (WGS84). Coordinates are ordered as [longitude, latitude]. The first and last positions in each ring must be identical (closed ring).

properties

object

Optional properties object. Any content is accepted and ignored by the API.

Request Example

{
  "type": "Feature",
  "geometry": {
    "type": "Polygon",
    "coordinates": [
      [
        [-8.5449, 42.8782],
        [-8.5400, 42.8782],
        [-8.5400, 42.8750],
        [-8.5449, 42.8750],
        [-8.5449, 42.8782]
      ]
    ]
  },
  "properties": {}
}

Validation

All geometry is validated before the spatial query runs. The first failing rule immediately returns an error — rules are checked in the order listed.

Rule	Error Code	HTTP
Valid JSON	`INVALID_JSON`	400
Valid GeoJSON Feature (or FeatureCollection with 1 feature)	`INVALID_GEOJSON`	400
Polygon or MultiPolygon geometry only	`INVALID_GEOMETRY_TYPE`	400
Single polygon per request	`MULTIPLE_FEATURES`	400
Valid topology (no self-intersections)	`INVALID_TOPOLOGY`	400
Inside Galicia bounding box `[-9.5, 41.5, -6.5, 44.0]`	`OUT_OF_BOUNDS`	400
Area ≤ 100 km²	`AREA_TOO_LARGE`	400
Vertices ≤ 10,000	`TOO_MANY_VERTICES`	400

Response — 200 OK

A successful response wraps the full analysis result under a top-level analysis key.

analysis

object

Top-level container for the analysis result.

Show analysis fields

analysis.parcel

object

Computed metadata about the submitted parcel.

Show parcel fields

area_m2

number

Parcel area in square metres, calculated in EPSG:25830 (UTM Zone 29N).

area_ha

number

Parcel area in hectares.

centroid

array

Parcel centroid as [longitude, latitude] in EPSG:4326.

crs_used

string

Coordinate reference system used for area computation. Always "EPSG:25830".

analysis.layers

array

Array of 7 layer result objects — one per environmental layer checked.

Show layer result fields

layer_name

string

Internal PostGIS table name for the layer (e.g., "red_natura_2000"). Use this key to correlate layer results with the /layers/status response.

display_name

string

Human-readable layer name used in the PDF report and UI (e.g., "Red Natura 2000").

affected

boolean

true if the submitted polygon intersects at least one feature in this layer.

features

array

List of intersecting features. Empty array when affected is false. Each feature object may contain: nombre, tipo, codigo, categoria, area_interseccion_m2, porcentaje_solape, and additional layer-specific fields such as periodo_retorno, nombre_cauce, anchura_legal_m, estado_ecologico, estado_quimico, or estado_cuantitativo.

analysis.summary

object

High-level summary of the analysis.

Show summary fields

total_layers_checked

integer

Always 7 — the number of environmental layers in the database.

layers_affected

integer

Number of layers where the polygon intersects at least one feature.

overall_risk

string

Derived risk level: "ninguno", "bajo", "medio", "alto", or "muy alto". See the risk scoring table below.

analysis.metadata

object

Metadata about the analysis execution.

Show metadata fields

analysis_duration_ms

number

Total time taken to run all PostGIS queries, in milliseconds.

Response Example

{
  "analysis": {
    "parcel": {
      "area_m2": 25430.5,
      "area_ha": 2.54,
      "centroid": [-8.5424, 42.8766],
      "crs_used": "EPSG:25830"
    },
    "layers": [
      {
        "layer_name": "red_natura_2000",
        "display_name": "Red Natura 2000",
        "affected": true,
        "features": [
          {
            "nombre": "Complexo húmido de Corrubedo",
            "tipo": "ZEC",
            "codigo": "ES1110006",
            "area_interseccion_m2": 12500.3,
            "porcentaje_solape": 49.15
          }
        ]
      },
      {
        "layer_name": "zonas_inundables",
        "display_name": "Zonas inundables (SNCZI)",
        "affected": false,
        "features": []
      },
      {
        "layer_name": "dominio_publico_hidraulico",
        "display_name": "Dominio Público Hidráulico",
        "affected": false,
        "features": []
      },
      {
        "layer_name": "vias_pecuarias",
        "display_name": "Vías pecuarias",
        "affected": false,
        "features": []
      },
      {
        "layer_name": "espacios_naturales_protegidos",
        "display_name": "Espacios Naturales Protegidos",
        "affected": true,
        "features": [
          {
            "nombre": "Parque Natural Corrubedo",
            "categoria": "Parque Natural",
            "area_interseccion_m2": 25430.5,
            "porcentaje_solape": 100.0
          }
        ]
      },
      {
        "layer_name": "masas_agua_superficial",
        "display_name": "Masas de agua superficiales",
        "affected": false,
        "features": []
      },
      {
        "layer_name": "masas_agua_subterranea",
        "display_name": "Masas de agua subterráneas",
        "affected": false,
        "features": []
      }
    ],
    "summary": {
      "total_layers_checked": 7,
      "layers_affected": 2,
      "overall_risk": "alto"
    },
    "metadata": {
      "analysis_duration_ms": 342
    }
  }
}

Risk Scoring Logic

The overall_risk field is derived from the layer intersection results. It is an indicative assessment and does not substitute a formal environmental study.

Condition	`overall_risk`
0 layers affected	`ninguno`
1–2 layers affected, all with < 10% overlap	`bajo`
1–2 layers affected, any with ≥ 10% overlap	`medio`
3+ layers affected, or Red Natura 2000 / ENP with ≥ 50% overlap	`alto`
Any intersection with Dominio Público Hidráulico, or flood zone with `periodo_retorno = "T100"`	`muy alto`

curl Example

curl -X POST https://geoviable.movilab.es/api/v1/analyze \
  -H "Content-Type: application/json" \
  -d '{"type":"Feature","geometry":{"type":"Polygon","coordinates":[[[-8.5449,42.8782],[-8.5400,42.8782],[-8.5400,42.8750],[-8.5449,42.8750],[-8.5449,42.8782]]]},"properties":{}}'

The frontend uses this endpoint to render a live preview of layer intersections on the map as the user draws a polygon. The /report/generate endpoint runs the full analysis independently when producing the PDF — it does not consume or cache the response from a prior /analyze call.

Overview

Endpoints

POST /api/v1/analyze — Spatial Analysis JSON Response

Request

Parameters

Request Example

Validation

Response — 200 OK

Response Example

Risk Scoring Logic

curl Example

Build docs developers (and LLMs) love

Overview

Endpoints

Documentation Index

​Request

​Parameters

​Request Example

​Validation

​Response — 200 OK

​Response Example

​Risk Scoring Logic

​curl Example

Build docs developers (and LLMs) love

Request

Parameters

Request Example

Validation

Response — 200 OK

Response Example

Risk Scoring Logic

curl Example