API hidrometeorológica · PISCO

API PISCO: precipitación y temperatura

Consulta precipitación PISCO v3 diaria y mensual, además de temperatura mínima y máxima diaria (Tmin/Tmax), para puntos, polígonos o multipolígonos dentro del Perú. Las respuestas JSON pueden integrarse directamente con Python, R, aplicaciones web y flujos de análisis hidrológico o geoespacial.

Precipitación:
v3 diaria y mensual

Temperatura:
Tmin / Tmax diaria

Geometría:
Point, Polygon, MultiPolygon

Salida:
JSON · mean / pixels

Endpoints disponibles

Base URL: https://fluviotech.com

Método

Endpoint

Variable

Formato de fecha

POST

/meteodata/pisco/monthly/series/

Precipitación mensual PISCO v3

YYYY-MM

POST

/meteodata/pisco/daily/series/

Precipitación diaria PISCO v3

YYYY-MM-DD

POST

/meteodata/api/pisco/temperature/daily/

Tmin / Tmax diaria PISCO v1

YYYY-MM-DD

Las geometrías usan GeoJSON en WGS84 / EPSG:4326 y el orden estándar [longitud, latitud].

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 /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]
    ]]
  }
}

Endpoint de temperatura diaria

POST /meteodata/api/pisco/temperature/daily/

Consulta tmin y/o tmax diaria. Si se omite variables, la API devuelve ambas. Para polígonos se admite aggregation: "mean" o aggregation: "pixels".

Ejemplo — Punto Tmin/Tmax

{
  "start": "2020-01-01",
  "end": "2020-01-10",
  "variables": ["tmin", "tmax"],
  "geometry": {
    "type": "Point",
    "coordinates": [-76.45, -7.25]
  }
}

Respuesta

{
  "datasets": {
    "tmin": "PISCO tmin v1 (daily)",
    "tmax": "PISCO tmax v1 (daily)"
  },
  "start": "2020-01-01",
  "end": "2020-01-10",
  "geometry_type": "Point",
  "requested_point": {"latitude": -7.25, "longitude": -76.45},
  "nearest_pixel": {"latitude": -7.25, "longitude": -76.45},
  "pixels_count": 1,
  "variables": ["tmin", "tmax"],
  "data": [
    {"date": "2020-01-01", "tmin": 12.4, "tmax": 24.8}
  ]
}

Con polígonos y aggregation: "mean", la salida usa tmin_mean y tmax_mean. Con aggregation: "pixels", cada registro incluye fecha, latitud, longitud y las variables solicitadas.

Snippets de código

Ejemplos listos para copiar. Todos usan Content-Type: application/json.

cURL — precipitación diaria en un punto

curl -X POST "https://fluviotech.com/meteodata/pisco/daily/series/" \
  -H "Content-Type: application/json" \
  -d '{
    "start":"2020-01-01",
    "end":"2020-01-10",
    "geometry":{"type":"Point","coordinates":[-76.45,-7.25]}
  }'

Python — precipitación mensual promedio de una cuenca

import json
import requests
import pandas as pd

with open("cuenca.geojson", encoding="utf-8") as f:
    geo = json.load(f)

if geo.get("type") == "FeatureCollection":
    geometry = geo["features"][0]["geometry"]
elif geo.get("type") == "Feature":
    geometry = geo["geometry"]
else:
    geometry = geo

url = "https://fluviotech.com/meteodata/pisco/monthly/series/"
payload = {
    "start": "1981-01",
    "end": "2020-12",
    "aggregation": "mean",
    "geometry": geometry,
}

response = requests.post(url, json=payload, timeout=120)
response.raise_for_status()
df = pd.DataFrame(response.json()["data"])
df["date"] = pd.to_datetime(df["date"])
print(df.head())

Python — temperatura diaria Tmin/Tmax

import requests
import pandas as pd

url = "https://fluviotech.com/meteodata/api/pisco/temperature/daily/"
payload = {
    "start": "2020-01-01",
    "end": "2020-01-31",
    "variables": ["tmin", "tmax"],
    "geometry": {
        "type": "Point",
        "coordinates": [-76.45, -7.25],
    },
}

response = requests.post(url, json=payload, timeout=120)
response.raise_for_status()
df = pd.DataFrame(response.json()["data"])
print(df.head())

R — precipitación diaria con httr2

library(httr2)
library(jsonlite)

payload <- list(
  start = "2020-01-01",
  end = "2020-01-10",
  geometry = list(
    type = "Point",
    coordinates = list(-76.45, -7.25)
  )
)

resp <- request("https://fluviotech.com/meteodata/pisco/daily/series/") |>
  req_body_json(payload) |>
  req_perform()

x <- resp_body_json(resp, simplifyVector = TRUE)
df <- as.data.frame(x$data)
print(head(df))

JavaScript — fetch desde una aplicación web

const response = await fetch(
  "https://fluviotech.com/meteodata/pisco/daily/series/",
  {
    method: "POST",
    headers: {"Content-Type": "application/json"},
    body: JSON.stringify({
      start: "2020-01-01",
      end: "2020-01-10",
      geometry: {
        type: "Point",
        coordinates: [-76.45, -7.25]
      }
    })
  }
);

if (!response.ok) throw new Error(`HTTP ${response.status}`);
const result = await response.json();
console.log(result.data);

Límites, errores y notas de uso

Rate limit: 60 solicitudes POST por hora e IP.
Área máxima por polígono: 250,000 km² por solicitud.
Coordenadas: GeoJSON estándar [longitud, latitud].
Sistema de referencia: WGS84 / EPSG:4326.
Resolución espacial: aproximadamente 0.1°.
Point: devuelve el píxel PISCO más cercano.
Polygon/MultiPolygon: use aggregation: "mean" para promedio espacial o "pixels" para datos distribuidos.
HTTP 400: fechas, geometría o parámetros inválidos.
HTTP 404: sin datos, dataset no registrado, geometría fuera del dominio o sin píxeles PISCO.
HTTP 413: polígono mayor al límite permitido.
HTTP 429: límite de solicitudes excedido.
HTTP 500: error al abrir o procesar el dataset.
SPI espacial: usar aggregation: "pixels".
Análisis de extremos: se recomienda priorizar estaciones observadas y usar PISCO como complemento.

Para consultas extensas con aggregation: "pixels", reduzca el periodo o divida la geometría para evitar respuestas JSON innecesariamente grandes.