Datasets

Plaza has three kinds of data: the OpenStreetMap planet, Plaza-curated datasets sourced from open data providers, and your own custom datasets. All three are queryable through the same API.

Plaza-curated datasets

Plaza sources and maintains open datasets from government agencies, transit authorities, and other public data providers. These cover things like building footprints, transit stops, land use boundaries, and other open geospatial data that isn’t in OpenStreetMap. They’re available to all users, kept in sync automatically, and each includes its own license and attribution metadata.

Custom datasets

Store your own GeoJSON features in Plaza and query them alongside everything else. Locations, boundaries, asset positions — anything with a geometry.

Create a dataset

curl -X POST https://plaza.fyi/api/v1/datasets \
  -H "x-api-key: $PLAZA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Store Locations",
    "description": "All retail locations in North America"
  }'

Response:

{
  "id": "ds_a1b2c3d4",
  "slug": "store-locations",
  "name": "Store Locations",
  "description": "All retail locations in North America",
  "feature_count": 0,
  "storage_bytes": 0,
  "status": "ready",
  "created_at": "2026-03-24T12:00:00Z"
}

The slug is auto-generated from the name. You’ll use it in PlazaQL queries.

Upload features

Upload a GeoJSON file with one of three modes:

Mode	Behavior
replace	Delete all existing features, insert new ones
merge	Upsert — match by feature ID, update existing, insert new
append	Add features without removing anything

# Replace all features from a file
curl -X POST https://plaza.fyi/api/v1/datasets/$DATASET_ID/upload \
  -H "x-api-key: $PLAZA_API_KEY" \
  -F "file=@stores.geojson" \
  -F "mode=replace"

The upload is processed asynchronously. The dataset status transitions from processing to ready once complete.

File size limits: 10 MB on the free tier, 500 MB on Pro plans.

Create individual features

For smaller updates, add features one at a time or in batches (up to 1,000 per request):

curl -X POST https://plaza.fyi/api/v1/datasets/$DATASET_ID/features \
  -H "x-api-key: $PLAZA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "features": [
      {
        "geometry": {
          "type": "Point",
          "coordinates": [-73.9856, 40.7484]
        },
        "properties": {
          "name": "NYC Flagship",
          "category": "retail"
        }
      }
    ]
  }'

Update a feature

curl -X PATCH https://plaza.fyi/api/v1/datasets/$DATASET_ID/features/$FEATURE_ID \
  -H "x-api-key: $PLAZA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "properties": {
      "name": "NYC Flagship (Renovated)",
      "status": "open"
    }
  }'

You can update the geometry, properties, or both.

Delete a feature

curl -X DELETE https://plaza.fyi/api/v1/datasets/$DATASET_ID/features/$FEATURE_ID \
  -H "x-api-key: $PLAZA_API_KEY"

Query features

REST API

List features from a dataset with cursor-based pagination:

# All features (default limit: 100)
curl -H "x-api-key: $PLAZA_API_KEY" \
  "https://plaza.fyi/api/v1/datasets/$DATASET_ID/features"

# With pagination
curl -H "x-api-key: $PLAZA_API_KEY" \
  "https://plaza.fyi/api/v1/datasets/$DATASET_ID/features?limit=50&after=$CURSOR"

You can also pass datasets as a query parameter on any standard query endpoint (/features, /nearby, /search, /query) to include custom dataset features in the results:

# Query OSM cafes + your store locations in the same bbox
curl -H "x-api-key: $PLAZA_API_KEY" \
  "https://plaza.fyi/api/v1/features?bbox=-74.01,40.70,-73.97,40.75&tags=amenity%3Dcafe&datasets=store-locations"

PlazaQL

Use the dataset() source function to query your data in PlazaQL:

// Query a single dataset
search(dataset("store-locations"))
  .around(1000, point(40.7484, -73.9856));

// Query multiple datasets
search(dataset("stores", "warehouses"))
  .within(boundary(name: "Manhattan"));

// Mix custom data with OSM features
search(dataset("stores"), node, amenity: "cafe")
  .within(boundary(name: "Manhattan"))
  .limit(20);

// Spatial join — find OSM restaurants near your locations
$locations = search(dataset("office-locations"));
search(node, amenity: "restaurant")
  .around(500, $locations);

All standard PlazaQL methods work on dataset results: .within(), .around(), .bbox(), .filter(), .limit(), .sort(), .fields(), .count, .skel, .ids, .tags.

List datasets

curl -H "x-api-key: $PLAZA_API_KEY" \
  "https://plaza.fyi/api/v1/datasets"

{
  "datasets": [
    {
      "id": "ds_a1b2c3d4",
      "slug": "store-locations",
      "name": "Store Locations",
      "description": "All retail locations in North America",
      "feature_count": 2847,
      "storage_bytes": 1048576,
      "status": "ready",
      "created_at": "2026-03-24T12:00:00Z"
    }
  ]
}

Delete a dataset

curl -X DELETE https://plaza.fyi/api/v1/datasets/$DATASET_ID \
  -H "x-api-key: $PLAZA_API_KEY"

Deletes the dataset and all its features. No undo.

SDK examples

TypeScript

import Plaza from "@plazafyi/sdk";

const client = new Plaza();

// Create a dataset
const ds = await client.v1.datasets.create({
  name: "Store Locations",
});

// Upload features
await client.v1.datasets.upload(ds.id, {
  file: fs.readFileSync("stores.geojson"),
  mode: "replace",
});

// Query via PlazaQL
const result = await client.v1.query.run({
  query: 'search(dataset("store-locations")).around(500, point(40.74, -73.99));',
});

Python

import plaza

client = plaza.Client()

# Create a dataset
ds = client.v1.datasets.create(name="Store Locations")

# Add features
client.v1.datasets.features.create(
    dataset_id=ds.id,
    features=[
        {
            "geometry": {"type": "Point", "coordinates": [-73.99, 40.74]},
            "properties": {"name": "NYC Flagship"},
        }
    ],
)

# Query via PlazaQL
result = client.v1.query.run(
    query='search(dataset("store-locations")).around(500, point(40.74, -73.99));'
)

Storage and billing

Every plan includes storage for custom datasets:

Plan	Storage included	Overage	Write rate limit
Free	1 MB	—	10/min
Pro 100K	1 GB	$5/GB/month	100/min
Pro 300K	5 GB	$5/GB/month	300/min
Pro 1M	20 GB	$5/GB/month	1,000/min
Enterprise	Custom	Custom	10,000/min

Write operations (create, update, delete features, upload) have separate rate limits from read queries.

Limits

Resource	Limit
Datasets per account	100
Features per dataset	1,000,000
Feature size	1 MB
Batch create	1,000 features per request
Datasets per query	20
Upload file size (Free)	10 MB
Upload file size (Pro)	500 MB

For higher limits, contact us about an Enterprise plan.

Use cases

Store locators. Upload locations, query by proximity. Combine with geocoding to find the nearest store to a customer address.

Custom boundaries. Sales territories, delivery zones, or franchise areas as polygons. Spatial queries check which zone a coordinate falls in.

Asset tracking. Update positions as assets move. Query by bounding box to see what’s in an area.

Data enrichment. Query your features against Plaza’s OSM data in the same request — find all restaurants within 500m of each office location.