Precipitation Geometry

🌧️ Cropped precision

Each polygon is pre-clipped to the exact circular area you queried — no post-processing needed on your side.

⚡ Binary-efficient

Protobuf encoding cuts payload size significantly compared to JSON, making it ideal for mobile and embedded clients.

🗺️ GeoJSON-ready

Two decode steps are all it takes to go from raw bytes to shapes you can drop straight into geojson.io or Mapbox.

What the endpoint returns

POST /v1/precipitations/geometry responds with a raw binary body (Content-Type: application/x-protobuf). The bytes encode a PrecipitationFeatureCollection message — a list of PrecipitationFeature items, each carrying a cropped MultiPolygon geometry and typed precipitation properties.

Do not try to parse the response body as JSON or text. It is a protobuf binary stream and will look like garbage if treated as a string.

Data source & update cadence 📡

Precipitation data is produced by the iklim.co precipitation service from radar observations.

Cadence: a new radar observation is processed every 10 minutes. radarTimestamp values of new records are aligned to a 10-minute UTC grid (e.g. 12:00, 12:10, 12:20).
Observation + forecast frames: each radar snapshot produces an observation (forecast: false) and forecast polygons at the configured offsets after the snapshot, up to the configured forecast horizon (forecast: true). The radarTimestamp of a forecast record is the time the forecast is valid for, so it lies in the future: set endTimeEpoch in the future (up to the forecast horizon) to retrieve forecast records.
Forecast records are short-lived: a forecast record is deleted once its valid time is reached; the radar observation for that time then arrives as a regular forecast: false record. Request the geometry of a forecast record before its valid time.
Retention: records are kept for 30 days.

Proto schema 📄

Below are the proto message definitions used by iklim.co for this endpoint.

// Shared geometry primitives
message Coordinate {
  double lng = 1;
  double lat = 2;
}

message Ring {
  repeated Coordinate coordinates = 1;
}

message PolygonShape {
  repeated Ring rings = 1;
}

message MultiPolygonShape {
  repeated PolygonShape polygons = 1;
}

message Geometry {
  enum GeometryType {
    POINT              = 0;
    LINE_STRING        = 1;
    POLYGON            = 2;
    MULTI_POINT        = 3;
    MULTI_LINE_STRING  = 4;
    MULTI_POLYGON      = 5;
    GEOMETRY_COLLECTION = 6;
  }

  GeometryType type = 1;

  oneof shape {
    Coordinate           point              = 2;
    LineStringShape      line_string        = 3;
    PolygonShape         polygon            = 4;
    MultiPointShape      multi_point        = 5;
    MultiLineStringShape multi_line_string  = 6;
    MultiPolygonShape    multi_polygon      = 7;
    GeometryCollectionShape geometry_collection = 8;
  }
}

// Precipitation-specific messages
// PrecipType is defined in iklim.co's precipitation.proto
// (package co.iklim.services.backend.common.dto.grpc.nowcast), which geojson.proto imports
enum PrecipType {
  PRECIP_TYPE_UNSPECIFIED = 0;   // type unknown (older records without a type)
  RAIN                    = 1;
  SNOW                    = 2;
}

message PrecipitationProperties {
  string     intensity        = 1;   // e.g. "DRIZZLE", "LIGHT", "MODERATE"
  int64      radar_timestamp  = 2;   // epoch milliseconds
  bool       forecast         = 3;   // true = forecast polygon (radar_timestamp is the valid time), false = radar observation
  PrecipType precip_type      = 4;   // RAIN or SNOW; PRECIP_TYPE_UNSPECIFIED on older records without a type
}

message PrecipitationFeature {
  string                   id         = 1;
  Geometry                 geometry   = 2;
  PrecipitationProperties  properties = 3;
}

message PrecipitationFeatureCollection {
  repeated PrecipitationFeature features = 1;
}

Copy the full geojson.proto file into your project before running the decoder steps below. The protobufjs loader needs the file at runtime.

Decoding & converting to GeoJSON 🛠️

Why two steps? GeoJSON is a JSON text format (RFC 7946) — it has no official protobuf schema. Its coordinates are bare nested arrays ([[lng, lat], ...]), which protobuf cannot represent without a named wrapper message. iklim.co’s binary schema uses typed messages (Coordinate, Ring, PolygonShape, …) optimised for compact encoding, so a structural reshaping step is always required after decoding.

Step-by-step guide 🪜
All-in-one snippet ⚡
GeoJSON output 📋

Install protobufjs 📦

npm install protobufjs
# or
yarn add protobufjs

Fetch the binary response 🌐

Tell fetch to read the response as an ArrayBuffer, then wrap it in a Uint8Array for the proto decoder.

const response = await fetch("/v1/precipitations/geometry", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": "Bearer <your-token>"
  },
  body: JSON.stringify({
    eventIds: ["69baa6b76e0fe76a1957273f", "4a1c3e9d8f2b07e5c6d4a1b2"],
    center: { lat: 36.80, lng: 32.33 },
    radius: 25000
  })
});

const buffer = await response.arrayBuffer();
const bytes  = new Uint8Array(buffer);

Decode the protobuf bytes 🔓

Load geojson.proto and decode the bytes into a JavaScript object.

import protobuf from "protobufjs";

const root = await protobuf.load("geojson.proto");
const PrecipitationFeatureCollection = root.lookupType(
  "PrecipitationFeatureCollection"
);

const fc = PrecipitationFeatureCollection.decode(bytes);

At this point fc looks like:

{
  "features": [{
    "id": "69baa6b76e0fe76a1957273f",
    "geometry": {
      "type": "MULTI_POLYGON",
      "multiPolygon": {
        "polygons": [{
          "rings": [{
            "coordinates": [
              { "lng": 32.33, "lat": 36.80 },
              { "lng": 32.34, "lat": 36.81 }
            ]
          }]
        }]
      }
    },
    "properties": {
      "intensity": "DRIZZLE",
      "radarTimestamp": 1773846600000,
      "forecast": false
    }
  }]
}

Convert to standard GeoJSON 🗺️

Transform the decoded object into RFC 7946-compliant GeoJSON.

function toGeoJson(fc) {
  return {
    type: "FeatureCollection",
    features: fc.features.map(feature => ({
      type: "Feature",
      id: feature.id,
      geometry: {
        type: "MultiPolygon",
        coordinates: feature.geometry.multiPolygon.polygons.map(polygon =>
          polygon.rings.map(ring =>
            ring.coordinates.map(coord => [coord.lng, coord.lat])
          )
        )
      },
      properties: {
        intensity:      feature.properties.intensity,
        radarTimestamp: feature.properties.radarTimestamp,
        forecast:       feature.properties.forecast
      }
    }))
  };
}

const geoJson = toGeoJson(fc);
console.log(JSON.stringify(geoJson, null, 2));

Drop this single async function into your project — it handles fetch, decode, and GeoJSON conversion end-to-end.

import protobuf from "protobufjs";

async function fetchPrecipitationGeoJson({ eventIds, center, radius, token }) {
  // 1 — Fetch binary response
  const response = await fetch("/v1/precipitations/geometry", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "Authorization": `Bearer ${token}`
    },
    body: JSON.stringify({ eventIds, center, radius })
  });

  if (!response.ok) throw new Error(`HTTP ${response.status}`);

  const bytes = new Uint8Array(await response.arrayBuffer());

  // 2 — Decode protobuf
  const root = await protobuf.load("geojson.proto");
  const PrecipitationFeatureCollection = root.lookupType(
    "PrecipitationFeatureCollection"
  );
  const fc = PrecipitationFeatureCollection.decode(bytes);

  // 3 — Convert to GeoJSON
  return {
    type: "FeatureCollection",
    features: fc.features.map(f => ({
      type: "Feature",
      id: f.id,
      geometry: {
        type: "MultiPolygon",
        coordinates: f.geometry.multiPolygon.polygons.map(poly =>
          poly.rings.map(ring =>
            ring.coordinates.map(c => [c.lng, c.lat])
          )
        )
      },
      properties: {
        intensity:      f.properties.intensity,
        radarTimestamp: f.properties.radarTimestamp,
        forecast:       f.properties.forecast
      }
    }))
  };
}

// Usage
const geoJson = await fetchPrecipitationGeoJson({
  eventIds: ["69baa6b76e0fe76a1957273f", "4a1c3e9d8f2b07e5c6d4a1b2"],
  center:   { lat: 36.80, lng: 32.33 },
  radius:   25000,
  token:    "<your-token>"
});

The final GeoJSON object is RFC 7946-compliant and renders correctly in any GeoJSON viewer.

{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "id": "69baa6b76e0fe76a1957273f",
      "geometry": {
        "type": "MultiPolygon",
        "coordinates": [
          [
            [
              [32.33, 36.80],
              [32.34, 36.81],
              [32.35, 36.80],
              [32.33, 36.80]
            ]
          ]
        ]
      },
      "properties": {
        "intensity": "DRIZZLE",
        "radarTimestamp": 1773846600000,
        "forecast": false
      }
    },
    {
      "type": "Feature",
      "id": "4a1c3e9d8f2b07e5c6d4a1b2",
      "geometry": {
        "type": "MultiPolygon",
        "coordinates": [
          [
            [
              [32.36, 36.82],
              [32.37, 36.83],
              [32.38, 36.82],
              [32.36, 36.82]
            ]
          ]
        ]
      },
      "properties": {
        "intensity": "MODERATE",
        "radarTimestamp": 1773848400000,
        "forecast": true
      }
    }
  ]
}

The second feature is a forecast polygon (forecast: true): its radarTimestamp is the time the forecast is valid for, one configured forecast offset after the radar snapshot.

🧪 Copy the output above and paste it into geojson.io to visually verify your geometry is correct before integrating with your map renderer.

Field reference 📚

`PrecipitationFeature`

Field	Type	Description
`id`	string	Unique identifier of the radar geometry record.
`geometry`	object	Cropped `MultiPolygon` geometry (see below).
`properties`	object	Typed precipitation metadata.

`geometry` (MultiPolygon)

Field	Path	Description
`type`	`geometry.type`	Always `MULTI_POLYGON` in the proto object; becomes `"MultiPolygon"` in GeoJSON.
`polygons`	`geometry.multiPolygon.polygons[]`	Array of polygons. Each polygon has one or more `rings`.
`rings`	`polygons[].rings[]`	First ring is the exterior boundary; additional rings are holes.
`coordinates`	`rings[].coordinates[]`	Array of `{ lng, lat }` objects → convert to `[lng, lat]` arrays for GeoJSON.

`properties`

Field	Type	Description
`intensity`	string	Precipitation intensity label. See the `IntensityType` catalog below.
`radarTimestamp`	number	UTC epoch milliseconds of the radar scan that detected this event; for forecast records (`forecast: true`), the time the forecast is valid for. Aligned to a 10-minute grid.
`forecast`	boolean	`false` = radar observation. `true` = forecast polygon at a configured offset after the radar snapshot, up to the configured forecast horizon.
`precipType`	number (enum `PrecipType`)	Precipitation type: `1` = `RAIN`, `2` = `SNOW`. `0` = `PRECIP_TYPE_UNSPECIFIED` (the proto3 default) on older records where the type is unknown.

Precipitation type (precipType) is returned in the protobuf properties (field precip_type = 4) and, as an optional field (RAIN or SNOW), on the JSON records of POST /v1/precipitations/within and POST /v1/precipitations/page. Records with a known type carry RAIN or SNOW; older records without a type carry PRECIP_TYPE_UNSPECIFIED in the protobuf and omit the field in JSON. It is additive: clients built with an older geojson.proto skip the new field and are not affected.

`IntensityType` catalog

Intensity classes are defined by radar reflectivity (dBZ). Rain and snow use separate bands. Reflectivity below 5 dBZ is treated as no precipitation and produces no polygon.

Value	Display name	Rain (dBZ)	Snow (dBZ)	Map color
`DRIZZLE`	Drizzle	5 ≤ dBZ < 20	5 ≤ dBZ < 10	`#7ae1e8`
`LIGHT`	Light	20 ≤ dBZ < 30	10 ≤ dBZ < 20	`#00c8d8`
`MODERATE`	Moderate	30 ≤ dBZ < 40	20 ≤ dBZ < 30	`#2d7bea`
`HEAVY`	Heavy	40 ≤ dBZ < 50	30 ≤ dBZ < 40	`#be46eb`
`VERY_HEAVY`	Very Heavy	50 ≤ dBZ < 60	dBZ ≥ 40	`#e36546`
`EXTREME`	Extreme	dBZ ≥ 60	not produced	`#ecd940`

EXTREME means reflectivity of 60 dBZ or more, large hail possible. It is not a direct hail detection. EXTREME is not produced for snow.

The dBZ bands above are the current thresholds. They may be tuned; any change will be announced in the release notes.

Before You Start

Webhook Alarms

MCP Server

Auth & User APIs

Accounts API

Lightning API

Thunderstorm API

Precipitation API

Forecast API

Point Alarm API

Region Alarm API

Forecast Alarm API

Enroute API

🌧️ Cropped precision

⚡ Binary-efficient

🗺️ GeoJSON-ready

What the endpoint returns

Data source & update cadence 📡

Proto schema 📄

Decoding & converting to GeoJSON 🛠️

Field reference 📚

`PrecipitationFeature`

`geometry` (MultiPolygon)

`properties`

`IntensityType` catalog

🌧️ Cropped precision

⚡ Binary-efficient

🗺️ GeoJSON-ready

​What the endpoint returns

​Data source & update cadence 📡

​Proto schema 📄

​Decoding & converting to GeoJSON 🛠️

​Field reference 📚

​PrecipitationFeature

​geometry (MultiPolygon)

​properties

​IntensityType catalog

What the endpoint returns

Data source & update cadence 📡

Proto schema 📄

Decoding & converting to GeoJSON 🛠️

Field reference 📚

`PrecipitationFeature`

`geometry` (MultiPolygon)

`properties`

`IntensityType` catalog