ingv-shakemap

How hard did the ground shake here? INGV's earthquakes and ShakeMap grids, read into numbers you can sample at any point in Italy.

grid = await IngvClient().shakemap(47606532)
grid.pga_g(15.55, 38.19)  # 0.0029 g in Messina, from the Mw 5.5 of 23 October 2026

• What is it, in 30 seconds
• Who is it for
• Quick start
• How it works
• Recipes
• The traps we already fell into
• API at a glance
• Data licence and credits

What is it, in 30 seconds

After every significant earthquake INGV publishes a ShakeMap: its estimate of how strongly the ground shook at every point around the epicentre, built from the stations that recorded it and from ground-motion models where there are none. The map is a grid.xml of up to 12 MB of text. This package turns it into arrays and answers questions about a point.

Who is it for

• Anyone who needs shaking at a site, not just a magnitude: a building, a dam, a road, the cells of a hazard model. Magnitude says how big the earthquake was; PGA says how hard it hit here.
• Landslide and multi-hazard models: earthquake-triggered landslides scale with ground acceleration, which this gives per point.
• Researchers and journalists who want INGV's own estimate rather than a distance-based guess.

It was extracted from Limen, the landslide, flood and wildfire monitor for Italy, where it reads the ShakeMap of every earthquake above magnitude 3.5 onto a 1 km grid. On three real grids its PGA matches Limen's own parser value for value.

Quick start

pip install ingv-shakemap

import asyncio
from datetime import UTC, datetime

from ingv_shakemap import IngvClient


async def main() -> None:
    async with IngvClient() as ingv:
        quakes = await ingv.events(
            datetime(2026, 10, 23, tzinfo=UTC),
            datetime(2026, 10, 24, tzinfo=UTC),
            min_magnitude=4.5,
        )
        for q in quakes:
            print(q.id, q.time, q.magnitude, q.magnitude_type, q.place)

        grid = await ingv.shakemap(quakes[1].id)  # None if INGV published no map
        if grid is not None:
            print(grid.map_status, grid.pga_g(15.55, 38.19), grid.mmi(15.55, 38.19))


asyncio.run(main())

47611152 2026-10-23 13:55:34.920000+00:00 5.0 Mw Tirreno Meridionale [Mare]
47606532 2026-10-23 10:19:15.470000+00:00 5.5 Mw Tirreno Meridionale [Mare]
47605832 2026-10-23 09:51:38.850000+00:00 4.8 Mw Tirreno Meridionale [Mare]
automatic 0.002939 3.4

How it works

flowchart LR
    F["INGV FDSN<br/>webservices.ingv.it"] -->|GeoJSON| E["parse_events<br/>Event"]
    E -->|event id| S["shakemap.ingv.it<br/>/data/{id}/current/products/grid.xml"]
    S -->|up to 12 MB of XML| G["parse_grid<br/>ShakeGrid"]
    G --> P["pga_g · pgv_cm_s · mmi<br/>value_at · column"]

The FDSN event id is the ShakeMap id: the same integer joins the two services.

Recipes

The shaking on many points at once. sample and sample_g take arrays of positions and answer in one NumPy call: on 100,000 points of a real grid, 10 ms against 280 ms for a loop over pga_g, with the same values. Outside the grid you get NaN:

pga = grid.sample_g("PGA", lons, lats)  # nearest point, in g
pga = grid.sample_g("PGA", lons, lats, method="bilinear")  # interpolated
pgv = grid.sample("PGV", lons, lats)  # native unit, cm/s

column still gives the whole grid as an (nlat, nlon) array, north row first.

Has the map changed? info reads info.json, a few kB, instead of the 12 MB grid: compare its version with the one you stored and download the grid only when it grew.

info = await ingv.info(event_id)
if info is not None and info.version != stored_version:
    grid = await ingv.shakemap(event_id)

How much of the map is measured. uncertainty is the map's standard deviation per point (STDPGA in ln g): low near the stations, high where the map is the ground-motion model alone. stations gives the stations themselves, what each recorded and what the model predicted there.

unc = await ingv.uncertainty(event_id)
sigma = unc.sample("STDPGA", lons, lats)
stations = await ingv.stations(event_id)
residuals = [s.pga_g / s.predicted_pga_g for s in stations if s.pga_g and s.predicted_pga_g]

Only what changed. events(..., updated_after=last_run) asks the catalogue for the events created or revised since then (FDSN updatedafter).

Parse in a thread. A big grid takes about a quarter of a second to parse. IngvClient.shakemap already runs it in asyncio.to_thread; when you parse yourself, do the same:

xml = await ingv.shakemap_xml(event_id)
grid = await asyncio.to_thread(parse_grid, xml)

Your own HTTP layer. Pass send, and the client uses it for every request and does no retrying of its own:

async def send(method: str, url: str, **kwargs):
    return await my_shared_policy(method, url, **kwargs)


ingv = IngvClient(send=send)

No network at all. parse_grid(Path("grid.xml").read_bytes()) and parse_events(json.loads(text)) work on files.

The traps we already fell into

1. PGA is in percent of g, not in g. The grid.xml writes units="%g": 0.11 is 0.0011 g, barely felt. pga_g converts; value_at("PGA", ...) and column("PGA") return the file's own unit.
2. The row order is a convention, not a statement. Rows go from the north edge southwards, longitude fastest. parse_grid checks this on the first rows and refuses a file in another order, because a wrong guess would move every value without raising.
3. The grid step changes from event to event: about 90 m at Campi Flegrei, 0.0083° (about 900 m) for the 23 October 2026 sequence. Never hard-code it; read lon_step and lat_step.
4. An empty week is a 204, an outage is not. The FDSN service answers 204 No Content to a window without earthquakes. A 5xx, even with no body, is a failure: events raises IngvError for it and returns [] only for the 204, so an unreachable catalogue never looks like a quiet week.
5. No ShakeMap is a 404, and it is normal. Small or very recent events have none: shakemap returns None. Any other error raises.
6. automatic can last, and the map keeps changing. The maps of the 23 October 2026 sequence still said map_status="automatic" twelve days later, and the Mw 5.5's went through four versions, the last one forty hours after the earthquake. A rule like "stable after 24 hours" misses it: compare info(event_id).version instead.
7. The old URL is dead. The /shake4/ prefix answered 404 for every event on 19 October 2026; the grid lives under /data/{id}/current/products/.
8. No top-level id in the GeoJSON. INGV puts the event id in properties.eventId, as an integer. parse_event reads it from there.
9. Times are UTC without an offset, both ways. The package sends 2026-10-23T10:19:15 and gives back aware UTC datetimes.
10. In stationlist.json a missing value is the string "null". 263 of the 469 stations of the Mw 5.5 have "pga": "null", as text. parse_stations reads it as None; a plain float() would raise, and a check for JSON null would let it through.

API at a glance

The full reference is on the documentation site.

Development

uv sync
make check   # ruff, mypy --strict, pytest with coverage
make docs    # the documentation site, built with --strict

Data licence and credits

• Earthquake catalogue: © Istituto Nazionale di Geofisica e Vulcanologia (INGV). The data and results published on terremoti.ingv.it are under CC BY 4.0: credit INGV.
• ShakeMap: computed and published by INGV at shakemap.ingv.it. That site states no licence of its own (checked on 4 November 2026); credit INGV as for the catalogue.
• ShakeMap is software by the USGS; the grid.xml format is ShakeMap 4's.

This package is not affiliated with INGV or the USGS. Code under Apache-2.0.