---
title: "Ground motion (subsidence or uplift, mm/year) of a parcel, 2020-2024"
method: GET
path: "/api/catastro/{refcat}/ground-motion"
tags: ["Hazards"]
---

# Ground motion (subsidence or uplift, mm/year) of a parcel, 2020-2024

`GET /api/catastro/{refcat}/ground-motion`

## Request

- Base URL: `https://api.parcelgps.com`
- URL: `https://api.parcelgps.com/api/catastro/{refcat}/ground-motion`
- Auth: API key in header `X-API-Key`

Satellite-measured vertical and east-west ground velocity over the parcel, its class, the fastest-sinking cell and the yearly displacement, for every country with a parcel outline inside EGMS coverage (EEA-39). Data: Copernicus Land Monitoring Service, European Ground Motion Service (free, commercial use allowed); the `source.attribution` string must be shown next to the data. Costs 1 unit of the monthly quota.

## Path parameters

- `refcat` string, required

## Query parameters

- `country` string

## Response `200`

Ground motion of the parcel, or `status: no_data` with the reason.

- GroundMotionResponse
  - `success` boolean
  - `data` GroundMotion: Ground motion of the parcel measured by satellite radar (Sentinel-1 InSAR), from the Copernicus European Ground Motion Service (EGMS) L3 Ortho product, 100 m grid, 2020-2024. Velocities are the mean over the 100 m cells whose centre falls inside the parcel outline; when no centre does (parcels under ~1 ha) or there is no outline, the 3 x 3 cells around the parcel point are used and `basis` says `surroundings`. Negative vertical velocity = the ground sinks. Fields with no measurement are left out instead of estimated.
    - `refcat` string, required
    - `country` string, required
    - `status` 'ok' | 'no_data' | 'unavailable', required: `no_data`: there is no measurement for this parcel (see `reason`). `unavailable`: our copy of the data could not be read; retry later.
    - `reason` 'no_reflectors' | 'outside_coverage' | 'parcel_too_large': Only with `no_data`. `no_reflectors`: the satellite found no stable reflectors here (fields, forest, water, snow); typical outside towns. `outside_coverage`: the location is outside EGMS coverage (EEA-39). `parcel_too_large`: the outline spans more than 2,500 km2.
    - `period` object, required
      - `from` string
      - `to` string
      - `label` string
    - `ground_motion` object
      - `class` 'severe_subsidence' | 'notable_subsidence' | 'slow_subsidence' | 'stable' | 'slow_uplift' | 'notable_uplift': From the mean vertical velocity v (mm/year): v <= -10 severe_subsidence; -10 < v <= -5 notable_subsidence; -5 < v <= -2 slow_subsidence; -2 < v < 2 stable; 2 <= v < 5 slow_uplift; v >= 5 notable_uplift.
      - `worst_class` string: Same scale applied to the fastest-sinking cell.
      - `vertical` object
        - `mean_mm_year` number
        - `max_subsidence_mm_year` number
        - `max_uplift_mm_year` number
        - `std_mm_year` number
        - `acceleration_mm_year2` number
        - `rmse_mm` number
      - `east_west` object: Positive = moving east.
        - `mean_mm_year` number
        - `std_mm_year` number
      - `yearly_displacement` object[]: Mean vertical displacement of each year relative to January 2020, in mm.
        - `year` integer
        - `mm` number
      - `cells_with_data` integer
      - `cells_considered` integer
      - `coverage_pct` number
      - `basis` 'parcel' | 'surroundings'
      - `cell_size_m` integer
    - `source` object, required: Name, provider, licence and the attribution that must be shown with the data.
      - `name` string
      - `provider` string
      - `license` string
      - `attribution` string
      - `url` string
      - `resolution` string
      - `edition` string
    - `calculated_at` string, date-time, required
    - `provenance` string

## Other responses

- `300`: CNV_AMBIGUOUS: bare digits that could be a reference of several countries. `data.candidates` lists them; repeat with `?country=`. Free.
- `400`: Malformed parameters (code VALIDATION_ERROR).
- `401`: Missing, malformed or unknown API key (KEY_AUTH_001, KEY_AUTH_002, KEY_AUTH_003, UNAUTHORIZED).
- `404`: The reference or address does not exist (code NOT_FOUND). Never used for outages.
- `422`: CNV_COVERAGE: the reference belongs to a country without coverage (`data.country`). CNV_PLACE_NAME: the text is a place name, not a reference. Free.
- `429`: KEY_AUTH_004: monthly quota used up and no prepaid balance left to cover the request (see X-Quota-*); nothing is charged. The message says the plan, the price per 1,000 extra units, where to top up and when the quota resets. KEY_RATE_002 or RATE_LIMIT_EXCEEDED: per-minute limit, wait Retry-After seconds.
- `503`: The official source of that country is down or saturated and our copy cannot answer (code SERVICE_UNAVAILABLE). Retry after Retry-After seconds. Free.

---

[API](https://skmtc.dev/catastrogps/apis/catastro-gps-api.md) · [All operations](https://skmtc.dev/catastrogps/apis/catastro-gps-api/llms.txt) · [OpenAPI document](https://skmtc.dev/catastrogps/apis/catastro-gps-api/revisions/1a86d44aa8ae?raw)