Skip to main content
GET
/
v1
/
api
/
tiles
/
buildings
/
metadata
Get Buildings Metadata
curl --request GET \
  --url https://api.bookovia.com/v1/api/tiles/buildings/metadata \
  --header 'X-API-Key: <api-key>'
{
  "success": true,
  "file": "<string>",
  "url": "<string>",
  "header": {
    "specVersion": 123,
    "minZoom": 123,
    "maxZoom": 123,
    "minLon": 123,
    "minLat": 123,
    "maxLon": 123,
    "maxLat": 123,
    "centerZoom": 123,
    "centerLon": 123,
    "centerLat": 123,
    "tileType": "<string>",
    "compression": "<string>",
    "tileDataSize": 123,
    "metadataSize": 123
  },
  "metadata": "<string>",
  "error": "<string>"
}

Documentation Index

Fetch the complete documentation index at: https://docs.bookovia.com/llms.txt

Use this file to discover all available pages before exploring further.

​
Overview

The Buildings Metadata endpoint returns detailed information about the buildings PMTiles archive, including zoom levels, geographic bounds, tile counts, and compression details.
This endpoint is useful for understanding tile coverage, data quality, and technical specifications of the buildings dataset.

​
Authentication

This endpoint requires authentication via API key in the X-API-Key header. Required permissions: maps:read

​
Request

No request parameters required.

​
Request Example

curl -H "X-API-Key: bkv_your_api_key_here" \
  https://api.bookovia.com/v1/api/tiles/buildings/metadata

​
Response

​
success
boolean
Indicates whether the request was successful
​
file
string
PMTiles filenameExample: usa-buildings.pmtiles
​
url
string
Direct URL to PMTiles archiveExample: https://maptiles.bookovia.com/usa-buildings.pmtiles
​
header
object
PMTiles header information
​
metadata
string
JSON-encoded metadata from PMTiles archiveContains layer schemas, attribution, and data source information

​
Response Example

{
  "success": true,
  "file": "usa-buildings.pmtiles",
  "url": "https://maptiles.bookovia.com/usa-buildings.pmtiles",
  "header": {
    "specVersion": 3,
    "minZoom": 0,
    "maxZoom": 15,
    "minLon": -179.1473,
    "minLat": 18.9110,
    "maxLon": -66.9498,
    "maxLat": 71.3577,
    "centerZoom": 4,
    "centerLon": -98.5795,
    "centerLat": 39.8283,
    "tileType": "mvt",
    "compression": "gzip",
    "tileDataSize": 9935166203,
    "metadataSize": 2048
  },
  "metadata": "{\"vector_layers\":[{\"id\":\"buildings\",\"fields\":{\"id\":\"String\",\"height\":\"Number\",\"building_type\":\"String\",\"address\":\"String\",\"num_floors\":\"Number\"},\"minzoom\":0,\"maxzoom\":15}],\"name\":\"USA Buildings\",\"description\":\"Building footprints from Overture Maps\",\"attribution\":\"© Overture Maps Foundation\"}"
}

​
Use Cases

Check the bounding box coordinates to verify that the dataset covers your application’s target area.
Use minZoom and maxZoom to determine appropriate zoom levels for displaying buildings in your application.
Extract attribution information from metadata to properly credit data sources in your application.
Parse the metadata JSON to discover available fields and their types for styling and filtering.

​
Understanding the Metadata

​
Geographic Coverage

// Bounding box for USA Buildings
const bounds = {
  west: -179.1473,   // Alaska (west)
  south: 18.9110,    // Hawaii/Puerto Rico
  east: -66.9498,    // Maine (east)
  north: 71.3577     // Alaska (north)
};

// Check if a location is within coverage
function isInCoverage(lat, lon) {
  return lat >= bounds.south && lat <= bounds.north &&
         lon >= bounds.west && lon <= bounds.east;
}

// Use center coordinates from metadata
const map = new maplibregl.Map({
  center: [-98.5795, 39.8283], // centerLon, centerLat
  zoom: 4 // centerZoom
});

​
Layer Schema

The metadata JSON includes the schema for the buildings layer: 
{
  "vector_layers": [
    {
      "id": "buildings",
      "fields": {
        "id": "String",
        "height": "Number",
        "building_type": "String",
        "address": "String",
        "num_floors": "Number"
      },
      "minzoom": 0,
      "maxzoom": 15
    }
  ]
}

​
Error Handling

​
error
string
Error message if the request failed

​
Common Errors

Status CodeErrorDescription
401API key requiredMissing X-API-Key header
401Invalid API key formatAPI key doesn’t start with bkv_
500Failed to fetch metadataArchive not available or network error

​
Best Practices

Cache metadata: Archive metadata doesn’t change frequently. Cache the response for 24-48 hours.
Validate coverage: Use the bounding box to ensure your application’s area of interest is covered before fetching tiles.
Extract attribution: Always display the attribution text from metadata to comply with data licensing requirements.
Use recommended center: The centerLon, centerLat, and centerZoom provide a good initial map view for the dataset.