Projection & Pagination (Options)

Many POST endpoints support an options object.

Depending on the endpoint, the following controls are available:

• Field projection (select)
• Offset pagination (skip, limit) – supported on viewport endpoints (/bbox/*)
• Cursor pagination (after_building_id) – supported on /query/buildings

Using these options correctly is essential for performance and scalability.

---

The options Object

Example structure:

{
  "options": {
    "select": ["building_id", "roof_area", "pv"],
    "skip": 0,
    "limit": 5000
  }
}

Not all options apply to all endpoints.
Cursor pagination is only supported by /query/buildings. Lookup endpoints (e.g., /buildings, /h3s, /postcodes, /municipalities, /buildings-coordinates) do not support pagination. They always return all matching records for the requested identifiers.

---

1️⃣ Projection (select)

Projection allows you to return only specific fields.

Example:

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

Important Rules

• The entity ID is always included automatically
• Fields not listed in select will not be returned
• Projection significantly reduces payload size
• Projection improves response time

---

Why Projection Matters

Without projection:

{
  "building_id": "...",
  "street": "...",
  "postcode": "...",
  "roof_area": 120,
  "geometry": {...},
  "roof_ids": [...],
  "roof_areas": [...],
  ...
}

With projection:

{
  "building_id": "...",
  "roof_area": 120
}

This can reduce payload size dramatically in map applications and bulk exports.

---

2️⃣ Offset Pagination (skip + limit)

Offset pagination works like traditional database paging.

Example:

{
  "options": {
    "skip": 0,
    "limit": 5000
  }
}

Parameters

• skip → number of records to skip (default: 0)
• limit → maximum number of records to return (default: 5000)

Example: Page 2

{
  "options": {
    "skip": 5000,
    "limit": 5000
  }
}

---

When to Use Offset Pagination

Suitable for:

• Small datasets
• Map viewport pagination
• Administrative UIs

Not recommended for:

• Large bulk exports

---

3️⃣ Cursor Pagination (Recommended for Large Exports)

Cursor pagination is supported by:

POST /query/buildings

Instead of using skip, the API returns a cursor token.

Example response:

{
  "returned": 5000,
  "next_after_building_id": "071e6c81dfcb86c8aa0baf44",
  "items": [...]
}

To fetch the next page:

{
  "region": {
    "postcode_in": ["90461"]
  },
  "options": {
    "limit": 5000,
    "after_building_id": "071e6c81dfcb86c8aa0baf44"
  }
}

Repeat until:

• next_after_building_id is not returned
• or returned is 0

---

Why Cursor Pagination Is Preferred

Offset pagination (skip) becomes slower for large offsets.

Cursor pagination:

• Is more efficient
• Is stable during long-running exports
• Is the recommended method for campaign workflows

---

4️⃣ Combining Projection and Pagination

Example bulk extraction:

{
  "region": {
    "ags_in": ["09564000"]
  },
  "filter": {
    "pv": false
  },
  "options": {
    "select": ["building_id", "postcode", "roof_area"],
    "limit": 5000
  }
}

Best practice:

• Always combine select with pagination
• Avoid retrieving unnecessary fields
• Use cursor paging for large exports

---

5️⃣ Limits & Defaults

If limit is not provided:

• A default value is applied (typically 5000)

Upper bounds may apply depending on endpoint and contract.

Always explicitly set limit in bulk workflows.

---

Common Mistakes

Missing Projection

Returning full building objects in map applications can cause performance issues.

Always use:

"select": ["building_id", "geometry"]

---

Mixing Skip and Cursor

Do not combine:

• skip
• after_building_id

Choose one pagination strategy per request.

---

Summary

The options object allows you to:

• Reduce payload size
• Control pagination
• Implement efficient bulk extraction
• Build scalable frontend integrations

For best performance:

• Always use select
• Prefer cursor pagination for large datasets
• Avoid large offsets with skip