Skip to main content
Most questions are answered by reading rows of Ploti’s official records where Ploti keeps them: a page of the parcels over five acres, a count of permits by month, the owner of one parcel number. These calls take a dataset id and answer in the same reply. They need no map and no download. They read layers and tables. Documents have their own calls.

​
Rows

datasets rows returns one page of rows.
  • columns: the columns you want, at most 100. Read real names from datasets get first.
  • where: a condition in CQL2-JSON, a standard way to write a filter as JSON. {"op": ">", "args": [{"property": "acreage"}, 5]} means acreage over 5. any_of takes a list of conditions, any of which a row may match.
  • place or bbox: a place, or a rectangle as west,south,east,north in degrees. Tables have no shapes and refuse both.
  • in_snapshot or not_in_snapshot: used by AI assistants working on a Ploti map, to read only the records they saved there as a snapshot (a saved set of rows on the map). Code that draws its own maps can leave these out.
  • geometry: how much of each shape to return: none, centroid (a point), area, bbox or full.
  • order_by: up to three columns to sort by.
  • limit and cursor: 100 rows unless you say. Pass the reply’s nextCursor to get the next page.
Every reply says how many rows matched and what place the rows came from. A cursor belongs to one request and one version of the dataset. If the dataset gets a new version while you page, the next call answers stale_cursor, and you start again.

​
Counts and totals

datasets aggregate answers with numbers instead of rows: count, sum, avg, min and max over up to 20 metrics, grouped by up to two columns, with the same conditions as a read. It returns at most 1,000 groups.

​
Look up by value

datasets lookup finds rows whose columns match the values you give, such as a parcel number, an address or an owner’s name, anywhere in the dataset, with no place needed. It takes up to 50 values, matched exactly or by contains, on up to 8 columns, and returns up to 50 rows. An exact match that finds nothing is tried again with spaces and dashes stripped, so 12-34-56 finds 123456.

​
Nearby and overlapping

datasets related takes one row, such as a parcel, by its dataset and row id. It finds the features of other layers that relate to it: those that intersect, touch, contain, overlap or lie within it, or lie within a distance of up to 5,000 meters. It checks up to 10 layers at a time and returns up to 1,000 features from each.

​
Size a read first

datasets estimate takes the same request as a read and says how many rows and bytes it would return, and how many pages that is, without returning any. Run it before anything large, then narrow the read with a place, a condition or fewer columns.

​
Limits

A page is capped by rows and by size, and the cap depends on the interface:
  • Each read stops after 30 seconds. A sorted read can page up to 50,000 rows in; an unsorted read can page through the whole dataset.
  • Each key runs at most 4 reads at once, and reads at most 300,000 rows, 500 MB and 120 seconds of query time a minute. datasets rows, aggregate, estimate and profile count toward it.
When you need more than a few pages, download the dataset instead. Limits and errors has the rest.