Download a dataset

ploti datasets download orange-parcels -o parcels.parquet \
  --place "Orange County, FL" --columns owner,acreage

import ploti

ploti.datasets.download(
    "orange-parcels",
    "parcels.parquet",
    place="Orange County, FL",
    columns=["owner", "acreage"],
)

curl -X POST https://api.ploti.ai/v1/datasets/orange-parcels/files \
  -H "Authorization: Bearer $PLOTI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"place": "Orange County, FL", "columns": ["owner", "acreage"]}'

No download over MCP: an assistant saves rows as a file on a Ploti map
with maps_files_export, which takes the map's map_id
(see Show results on a map).

ploti datasets download orange-parcels -o parcels.parquet \
  --place "Orange County, FL" --columns owner,acreage

import ploti

ploti.datasets.download(
    "orange-parcels",
    "parcels.parquet",
    place="Orange County, FL",
    columns=["owner", "acreage"],
)

curl -X POST https://api.ploti.ai/v1/datasets/orange-parcels/files \
  -H "Authorization: Bearer $PLOTI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"place": "Orange County, FL", "columns": ["owner", "acreage"]}'

No download over MCP: an assistant saves rows as a file on a Ploti map
with maps_files_export, which takes the map's map_id
(see Show results on a map).

Download a dataset when you want the rows themselves: to join with your own data, load into a database or analyze with your own tools. A dataset is one set of official records Ploti holds, such as a county’s parcels. A download writes its rows to a file on your machine as GeoParquet. That is Parquet, a compact table format most data tools read, with each row’s shape included. Your workspace’s Ploti plan is all it needs: no map, and no Data Feeds subscription. A download is a copy as of today. To have each new version delivered as the source changes, use Data Feeds. Without it, staying current means downloading the dataset again.

Whole or a cut

A whole download has no condition, place, box or snapshot, and has geometry full or none. It comes straight from the files Ploti stores for the dataset. It is then trimmed to the columns you name, or every public column when you name none, and merged into one file. It is the fastest way to get a whole county. A cut is narrowed by any of those. Ploti makes it on its servers first, so only the rows you asked for download. Narrowing a large layer by place keeps the file small. A cut that takes a while runs as a job: the reply carries a job id, and jobs get reports when it’s done. The CLI and Python wait for it on their own. datasets download takes the same conditions as datasets rows, plus where to write:

Option	Effect
`-o`, `--out`	The file to write; `<dataset>.parquet` when left out. `.parquet` writes one GeoParquet file, with shapes as WKB (a standard binary form). `.ndjson`, `.geojson` or `.csv` converts the rows, with shapes as GeoJSON.
`--columns`	Comma-separated columns. Left out, every public column.
`--where`, `--any-of`	Conditions in CQL2-JSON, as `datasets rows` takes them.
`--place`, `--bbox`	A place, or `west,south,east,north` in degrees.
`--in-snapshot`, `--not-in-snapshot`	Only the rows in, or outside, a snapshot.
`--geometry`	`none`, `centroid`, `area`, `bbox` or `full` (the default).

Before you start:

Run datasets estimate with the same conditions to learn how many rows and bytes the download would be.
The download checks the disk has room before it writes.
Merging several files into one, trimming columns, and converting to .ndjson, .csv or .geojson all read the Parquet files. For that, the CLI needs Node.js 22.15 or later, and Python needs pyarrow, which the [parquet] extra installs.

Over REST

POST /v1/datasets/{dataset}/files takes the same request and answers with links to the GeoParquet files, which you download and merge yourself. The links last an hour. A cut that takes a while answers with a jobId instead; poll GET /v1/jobs/{jobId} until it’s done.

Over MCP

An AI assistant without a disk of its own can’t download. It makes a Ploti map and saves the rows as a file on it with maps_files_export instead. Show results on a map explains how. Code with a disk uses the CLI, Python or REST.

Other kinds and limits

Documents download as text with documents download, and collections one document at a time.
A dataset outside your workspace’s coverage areas is refused.

A dataset’s stored files

Ploti keeps the files behind each dataset. datasets files get returns one, named by file:

original: the document PDF or scanned map image Ploti downloaded for the data it publishes now.
source:<id>: Ploti’s archived copy of one source, with its id from datasets provenance.
document:<sha256>: a file a row cites, such as a permit’s scanned application, named in the row’s cell.

The reply carries three things:

a downloadUrl that lasts 5 minutes
a lasting link that checks your access each time it is opened
the file’s sha256 checksum, so you can check the bytes you received

Any kind of dataset can have stored files.

Use the files

GeoParquet works with most data tools. In DuckDB:

INSTALL spatial; LOAD spatial;

SELECT count(*), avg(acreage)
FROM read_parquet('parcels.parquet');

Pandas and GeoPandas read it with read_parquet, and QGIS opens it as a layer.

ploti datasets download orange-parcels -o parcels.parquet \
  --place "Orange County, FL" --columns owner,acreage

import ploti

ploti.datasets.download(
    "orange-parcels",
    "parcels.parquet",
    place="Orange County, FL",
    columns=["owner", "acreage"],
)

curl -X POST https://api.ploti.ai/v1/datasets/orange-parcels/files \
  -H "Authorization: Bearer $PLOTI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"place": "Orange County, FL", "columns": ["owner", "acreage"]}'

No download over MCP: an assistant saves rows as a file on a Ploti map
with maps_files_export, which takes the map's map_id
(see Show results on a map).

Start here

Own the data

Query Ploti directly

Data Feeds API reference

Download a dataset

Whole or a cut

Over REST

Over MCP

Other kinds and limits

A dataset’s stored files

Use the files

​Whole or a cut

​Over REST

​Over MCP

​Other kinds and limits

​A dataset’s stored files

​Use the files

Whole or a cut

Over REST

Over MCP

Other kinds and limits

A dataset’s stored files

Use the files