> ## Documentation Index
> Fetch the complete documentation index at: https://ploti.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Download a dataset

> Download a layer's or table's rows as GeoParquet, whole or cut by place, condition and columns, and get the original files Ploti stores for any dataset

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](https://ploti.ai/docs/feeds/overview.md). 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`](https://ploti.ai/docs/developers/read-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`](https://ploti.ai/docs/developers/read-rows#size-a-read-first) 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](https://ploti.ai/docs/mcp/maps.md#show-and-share) explains how. Code with a disk uses the CLI, Python or REST.

## Other kinds and limits

* [Documents](https://ploti.ai/docs/developers/documents.md) download as text with `documents download`, and [collections](https://ploti.ai/docs/developers/documents.md#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:

```sql theme={null}
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.

```bash CLI theme={null}
ploti datasets download orange-parcels -o parcels.parquet \
  --place "Orange County, FL" --columns owner,acreage
```

```python Python theme={null}
import ploti

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

```bash REST theme={null}
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"]}'
```

```text MCP theme={null}
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).
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.