Skip to content

Lookup Patterns

Lookup endpoints allow you to retrieve specific entities directly by identifier or coordinate.

They are optimized for:

  • Detail views
  • Backend validation
  • CRM enrichment
  • Entity resolution
  • Debugging and QA workflows

Lookup endpoints return complete records unless projection is supported and explicitly requested.

1️⃣ Single Building Lookup

By Building ID

GET /building

Required Parameters

  • building_id
  • subscription_key

Example

curl "https://ua-api-solar-lake-enterprise.azurewebsites.net/building?building_id=01c02e568d94065d29c7fd9e&subscription_key=YOUR_KEY"

When to Use

  • Opening a building detail page
  • Fetching full solar potential metrics
  • Inspecting roof-level information
  • Backend verification of an ID

By Coordinates

GET /building-coordinates

Returns a building for the provided WGS84 coordinate using containment-first matching:

  1. Resolve the building if the point lies inside a footprint.
  2. Otherwise, fall back to the nearest building within 2 meters.
  3. Return the fallback only when exactly one building is within that radius.
  4. Otherwise, return no match.

Required Parameters

  • lon
  • lat
  • subscription_key

Example

curl "https://ua-api-solar-lake-enterprise.azurewebsites.net/building-coordinates?lon=7.1202&lat=51.481&subscription_key=YOUR_KEY"

When to Use

  • Map click interaction
  • Address-to-building resolution
  • Coordinate-based enrichment

2️⃣ Batch Building Lookup

By IDs

POST /buildings

Example

{
  "building_ids": [
    "01c495b5658638dac98ece60",
    "024dbe18626eb27678f0eae2"
  ],
  "options": {
    "select": ["building_id", "roof_area", "pv"]
  }
}

Response Structure

{
  "requested": 2,
  "returned": 2,
  "missing_ids": [],
  "items": [...]
}

When to Use

  • CRM enrichment
  • Validation of multiple IDs
  • Batch detail retrieval

By Coordinates (Batch)

POST /buildings-coordinates

Example

{
  "points": [
    { "lon": 7.1202, "lat": 51.4811 },
    { "lon": 6.7802, "lat": 51.1583 }
  ],
  "options": {
    "select": ["building_id", "postcode"]
  }
}

Response Includes

  • requested
  • returned
  • missing_points
  • items

Each item contains:

  • input_point → the original coordinate
  • match_type → inside or nearest_within_2m
  • building → the resolved building object

This allows deterministic mapping between inputs and results, even when duplicates or partial matches occur.

3️⃣ H3 Lookup

Single H3 Cell

GET /h3

Required

  • h3_id
  • subscription_key

H3 ID may be decimal or hex.

Example:

curl "https://ua-api-solar-lake-enterprise.azurewebsites.net/h3?h3_id=613046256849125375&subscription_key=YOUR_KEY"

Batch H3 Lookup

POST /h3s

{
  "h3_ids": [
    "613046256849125375",
    "613046255204958207"
  ],
  "options": {
    "select": ["h3_id", "count_buildings"]
  }
}

4️⃣ Postcode Lookup

Single Postcode

GET /postcode

curl "https://ua-api-solar-lake-enterprise.azurewebsites.net/postcode?postcode=90461&subscription_key=YOUR_KEY"

Batch Postcode Lookup

POST /postcodes

{
  "postcodes": ["90461", "90471"],
  "options": {
    "select": ["postcode", "count_buildings"]
  }
}

5️⃣ Municipality Lookup

Single Municipality

GET /municipality

curl "https://ua-api-solar-lake-enterprise.azurewebsites.net/municipality?ags=09564000&subscription_key=YOUR_KEY"

Batch Municipality Lookup

POST /municipalities

{
  "ags_list": ["09564000", "09562000"],
  "options": {
    "select": ["ags", "municipality", "state", "count_buildings"]
  }
}

Typical Lookup Use Cases

Detail Page Workflow

  1. User selects building on map
  2. Frontend retrieves building_id
  3. Call GET /building
  4. Render detailed solar metrics

CRM Enrichment

  1. Export building IDs from campaign
  2. Send batch request to /buildings
  3. Merge response into CRM

Validation Workflow

  1. External system sends ID list
  2. Use batch lookup
  3. Check missing_ids for invalid entries

Performance Recommendations

  • Use projection (options.select) in batch lookups
  • Avoid retrieving full geometry if not required
  • Use batch endpoints instead of multiple single GET calls
  • Limit batch size to reasonable numbers (e.g., hundreds, not tens of thousands)

Error Handling

Batch endpoints return:

  • requested
  • returned
  • missing_ids or missing_points

Always validate:

requested == returned

If not, inspect the missing entries.

Summary

Lookup endpoints are optimized for:

  • Direct entity retrieval
  • Batch enrichment
  • Coordinate resolution
  • Administrative lookups

They are ideal for backend services, CRM integrations, and detailed user interfaces.