API hidrometeorológica · PISCO v3

API PISCO v3

Consulta datos de precipitación PISCO v3 diaria y mensual para puntos, polígonos o multipolígonos dentro del Perú. Las respuestas se entregan en formato JSON y pueden integrarse directamente con Python, pandas, geopandas y flujos de análisis hidrológico.

Formato:
JSON

Geometría:
Point, Polygon, MultiPolygon

Uso:
Series, SPI, análisis espacial

Endpoint mensual

POST /meteodata/pisco/monthly/series/

Parámetros de entrada

Campo	Tipo	Requerido	Descripción
`start`	string	Sí	Fecha inicial en formato `YYYY-MM`. Ejemplo: `1981-01`.
`end`	string	Sí	Fecha final en formato `YYYY-MM`.
`geometry`	GeoJSON	Sí	Geometría tipo `Point`, `Polygon` o `MultiPolygon` en WGS84.
`aggregation`	string	No	Para polígonos: `mean` o `pixels`. Por defecto usa `mean`.

Ejemplo — Punto

POST /meteodata/pisco/monthly/series/

{
  "start": "1981-01",
  "end": "2020-12",
  "geometry": {
    "type": "Point",
    "coordinates": [-76.45, -7.25]
  }
}

Respuesta

{
  "dataset": "PISCO precipitation v3 (monthly)",
  "start": "1981-01",
  "end": "2020-12",
  "geometry_type": "Point",
  "data": [
    {"date": "1981-01", "precipitation": 47.34},
    {"date": "1981-02", "precipitation": 100.74}
  ]
}

Polígono con agregación media

aggregation: "mean"

{
  "start": "1981-01",
  "end": "2020-12",
  "geometry": {
    "type": "Polygon",
    "coordinates": [[
      [-75.0, -12.0],
      [-74.0, -12.0],
      [-74.0, -11.0],
      [-75.0, -11.0],
      [-75.0, -12.0]
    ]]
  }
}

Respuesta

{
  "dataset": "PISCO precipitation v3 (monthly)",
  "geometry_type": "Polygon",
  "pixels_count": 100,
  "data": [
    {"date": "1981-01", "precipitation_mean": 328.9},
    {"date": "1981-02", "precipitation_mean": 273.15}
  ]
}

Polígono con datos por píxel

aggregation: "pixels"

Recomendado para cálculos de SPI espacial, mapas de sequía o análisis distribuido por celda PISCO.

{
  "start": "1981-01",
  "end": "2020-12",
  "aggregation": "pixels",
  "geometry": {
    "type": "Polygon",
    "coordinates": [[
      [-75.0, -12.0],
      [-74.0, -12.0],
      [-74.0, -11.0],
      [-75.0, -11.0],
      [-75.0, -12.0]
    ]]
  }
}

Respuesta

{
  "dataset": "PISCO precipitation v3 (monthly)",
  "geometry_type": "Polygon",
  "aggregation": "pixels",
  "pixels_count": 51,
  "records_count": 612,
  "data": [
    {
      "date": "1981-01",
      "latitude": -7.25,
      "longitude": -76.45,
      "precipitation": 47.34
    }
  ]
}

Endpoint diario

POST /api/meteodata/pisco/daily/series/

Usa la misma estructura del endpoint mensual, pero las fechas deben enviarse en formato YYYY-MM-DD.

{
  "start": "1981-01-01",
  "end": "1981-01-31",
  "geometry": {
    "type": "Polygon",
    "coordinates": [[
      [-75.0, -12.0],
      [-74.0, -12.0],
      [-74.0, -11.0],
      [-75.0, -11.0],
      [-75.0, -12.0]
    ]]
  }
}

Ejemplo en Python

import requests
import pandas as pd

url = "https://fluviotech.com/meteodata/pisco/monthly/series/"

payload = {
    "start": "1981-01",
    "end": "2020-12",
    "aggregation": "pixels",
    "geometry": {
        "type": "Polygon",
        "coordinates": [[
            [-75.0, -12.0],
            [-74.0, -12.0],
            [-74.0, -11.0],
            [-75.0, -11.0],
            [-75.0, -12.0]
        ]]
    }
}

response = requests.post(url, json=payload)
response.raise_for_status()

result = response.json()
df = pd.DataFrame(result["data"])
df["date"] = pd.to_datetime(df["date"])

print(df.head())

Notas de uso

Coordenadas: usar GeoJSON estándar: [longitud, latitud].
Sistema de referencia: WGS84 / EPSG:4326.
Resolución espacial: aproximadamente 0.1°.
SPI espacial: usar aggregation: "pixels".
Análisis de extremos: se recomienda priorizar estaciones observadas y usar PISCO como complemento.