--- title: Datasets | Plaza Docs description: Upload your own GeoJSON feature collections and query them alongside OpenStreetMap data. --- 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 Terminal window ``` 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 | Terminal window ``` # 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): Terminal window ``` 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 Terminal window ``` 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 Terminal window ``` 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: Terminal window ``` # 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: Terminal window ``` # 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 Terminal window ``` 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 Terminal window ``` 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.