Exclusion (Incremental Loading)

Some POST endpoints support an exclude object that allows you to prevent previously loaded data from being returned again.

This feature is particularly useful for:

• Interactive map applications
• Incremental viewport loading
• Avoiding duplicate data transfers
• Optimizing frontend performance

---

Supported Endpoints

Exclusion is supported by advanced POST bbox endpoints:

• POST /bbox/buildings
• POST /bbox/h3s
• POST /bbox/postcodes
• POST /bbox/municipalities

---

Exclusion Structure

The exclude object can contain:

{
  "exclude": {
    "exclude_ids": [...],
    "exclude_bboxes": [...]
  }
}

Both fields are optional.

---

1️⃣ Excluding by IDs

You can exclude specific entities by ID.

Example (exclude specific buildings):

{
  "bbox": {
    "min_lon": 11.5,
    "min_lat": 48.1,
    "max_lon": 11.505,
    "max_lat": 48.105
  },
  "exclude": {
    "exclude_ids": [
      "dec4d1435bfe97a70b690910",
      "f4a380fbd94559bbc12aabb7"
    ]
  }
}

Use cases:

• Prevent re-rendering already loaded objects
• Remove specific items from viewport reloads

The interpretation of IDs depends on the endpoint:

• Buildings → building IDs
• H3 → H3 IDs
• Postcodes → postcode strings
• Municipalities → AGS codes

---

2️⃣ Excluding by Bounding Boxes

You can exclude entire sub-areas of a larger viewport.

Example:

{
  "bbox": {
    "min_lon": 11.5,
    "min_lat": 48.1,
    "max_lon": 11.51,
    "max_lat": 48.11
  },
  "exclude": {
    "exclude_bboxes": [
      {
        "min_lon": 11.505,
        "min_lat": 48.105,
        "max_lon": 11.51,
        "max_lat": 48.11
      }
    ]
  },
  "options": {
    "select": ["building_id", "geometry"]
  }
}

This instructs the API:

• Return results for the full outer bounding box
• Except for the excluded sub-area

---

Typical Map Workflow

1. User opens map → load initial bbox
2. Store loaded bbox
3. User pans slightly
4. Send new request:
   • Expanded bbox
   • Exclude previous bbox
5. Render only newly returned items

Pseudo-logic:

initial_bbox = current_map_bounds
request(initial_bbox)

on_pan():
    new_bbox = current_map_bounds
    request({
        bbox: new_bbox,
        exclude: { exclude_bboxes: [initial_bbox] }
    })

---

When to Use Exclusion

Use exclusion when:

• Map panning occurs frequently
• Large building datasets are displayed
• You want to minimize repeated payload transfer
• Frontend stores previously loaded data

Do not use exclusion when:

• Data changes frequently
• You need a fully refreshed dataset
• You require strict bounding box isolation

---

Combining Exclusion with Filters

Exclusion works together with filtering and projection.

Example:

{
  "bbox": {
    "min_lon": 11.5,
    "min_lat": 48.1,
    "max_lon": 11.51,
    "max_lat": 48.11
  },
  "filter": {
    "pv": false
  },
  "exclude": {
    "exclude_bboxes": [
      {
        "min_lon": 11.505,
        "min_lat": 48.105,
        "max_lon": 11.51,
        "max_lat": 48.11
      }
    ]
  },
  "options": {
    "select": ["building_id", "geometry"],
    "limit": 5000
  }
}

This ensures:

• Only buildings without PV
• Only new areas are returned
• Payload is minimized

---

Performance Considerations

Exclusion improves performance by:

• Reducing duplicate data transfer
• Lowering frontend rendering overhead
• Minimizing server-side result size

However:

• The frontend must correctly track previously loaded areas
• Overlapping exclusions may reduce clarity
• Excessively fragmented exclusions may add complexity

---

Best Practices

• Use exclude_bboxes for viewport-based map loading
• Use exclude_ids for specific object-level exclusion
• Always combine exclusion with select
• Keep exclusion logic simple and predictable

---

Summary

The exclude mechanism enables efficient incremental data loading.

It is especially valuable for:

• High-performance web map applications
• Large building datasets
• Repeated viewport updates

When used correctly, exclusion significantly improves responsiveness and reduces network traffic.