Skip to content

Conventions

This section describes general conventions used across the Solar Lake Enterprise API.

Understanding these conventions will help you integrate the API efficiently and avoid common pitfalls.

Coordinate System

All geographic coordinates use:

WGS84 (EPSG:4326)
Format: longitude, latitude

Example:

{
  "lon": 11.42,
  "lat": 48.69
}

Note that coordinates inside the supported area (Germany) are only within:

  • lon ∈ [5, 16]
  • lat ∈ [46, 56]

Bounding Boxes

Bounding boxes must be provided using:

{
  "min_lon": 11.5,
  "min_lat": 48.1,
  "max_lon": 11.6,
  "max_lat": 48.2
}

Rules:

  • min_lon < max_lon
  • min_lat < max_lat
  • Longitude range: -180 to 180
  • Latitude range: -90 to 90

Bounding box queries are optimized for performance.
Results may include a small number of objects slightly outside the requested bounding box.

Geometry Format

Geometry fields are returned as GeoJSON objects.

Examples:

Point (Building Location)

{
  "type": "Point",
  "coordinates": [11.42, 48.69]
}

Polygon (Building Footprint or Aggregates)

{
  "type": "Polygon",
  "coordinates": [
    [
      [11.41, 48.69],
      [11.42, 48.69],
      [11.42, 48.70],
      [11.41, 48.70],
      [11.41, 48.69]
    ]
  ]
}

Coordinates follow GeoJSON standards: [longitude, latitude].

ID Fields

The API uses consistent ID formats across endpoints.

ID fields are always included in projection-based responses.

Building IDs

  • 24-character hexadecimal string
  • Example: 7318d62032d225284c7a97cf

H3 IDs

  • Accepted as decimal or hexadecimal
  • Returned in decimal representation
    • Example: 622053459255459839

Postcode

  • 5-character string

Note that German postcodes might begin with 0 and therefore should not be stored as numbers

Municipality (AGS)

Filtering Syntax

Advanced POST endpoints support a Mongo-like filter syntax.

Supported operators:

  • $eq – equals
  • $ne – not equals
  • $gt – greater than
  • $gte – greater than or equal
  • $lt – less than
  • $lte – less than or equal
  • $in – value in list
  • $nin – value not in list

Example:

{
  "roof_area": { "$gte": 100 },
  "pv": false,
  "building_type": { "$in": ["single-family house", "terraced house"] }
}

Only documented fields are filterable.

Projection (options.select)

To reduce response size and improve performance, you can request specific fields:

{
  "options": {
    "select": ["building_id", "roof_area", "pv"]
  }
}

Notes:

  • The entity ID is always included automatically.
  • Fields not listed in select will not be returned.

Using projection is strongly recommended for map applications and large exports.

Pagination

Pagination is supported on viewport (/bbox/*) and bulk extraction (/query/buildings) endpoints.

Lookup endpoints (e.g., /buildings, /h3s, /postcodes, /municipalities) do not support pagination and always return all requested identifiers.

Offset Pagination

{
  "options": {
    "skip": 0,
    "limit": 5000
  }
}
  • skip defaults to 0
  • limit defaults to 5000
  • Maximum limits may apply

Offset pagination is suitable for small datasets.

Used with:

POST /query/buildings

Response includes:

{
  "next_after_building_id": "a81c82ebb2f46da58c237741"
}

Use this value in the next request:

{
  "options": {
    "after_building_id": "a81c82ebb2f46da58c237741"
  }
}

Cursor pagination is the recommended approach for bulk workflows.

Exclusion (Incremental Loading)

Advanced bbox endpoints support excluding previously loaded data.

Example:

{
  "exclude": {
    "exclude_bboxes": [
      {
        "min_lon": 11.55,
        "min_lat": 48.15,
        "max_lon": 11.56,
        "max_lat": 48.16
      }
    ]
  }
}

This is useful for incremental viewport loading in map applications.

Response Structure Conventions

Many responses include summary metadata:

{
  "returned": 5000,
  "items": [...]
}

Bounding box responses additionally include:

{
  "h3_resolution": 7,
  "cells": 120,
  "cells_truncated": false,
  "returned": 5000,
  "items": [...]
}

Where:

  • h3_resolution – resolution used internally for aggregation
  • cells – number of H3 cells covering the bounding box
  • cells_truncated – True if the H3 cover was truncated by a server safety cap
  • returned – number of documents returned

Error Handling

Validation Errors (HTTP 422)

If request parameters are invalid, the API returns:

{
  "detail": [
    {
      "loc": ["query", "min_lon"],
      "msg": "value is not a valid number",
      "type": "type_error.number"
    }
  ]
}

Empty Results

If no matching records exist, the API returns:

{
  "returned": 0,
  "items": []
}

This is not an error.

Performance Guidelines

For best performance:

  • Use options.select to reduce payload size
  • Avoid overly large bounding boxes
  • Prefer cursor pagination for bulk exports
  • Use POST bbox endpoints when filtering or excluding data