Skip to main content
Before you read anything from Ploti, find the dataset that holds it. A dataset is one set of official records from one source, such as a county’s parcels. A search takes plain words, such as “building permits” or “flood zones”, and returns the matching datasets, ranked. Each comes with the dataset id every other call takes. You can narrow a search by place, topic or kind, and it tells you when a match exists outside your coverage areas, the counties your workspace pays for.

​
Places

A place narrows a search, a read or a subscription to part of the country. places list returns the places your workspace covers, with ids you can pass anywhere a call takes a place: A read also takes a plain name, such as "Orange County, FL", or a city, such as "Sanford, FL". A city is read as the area its boundary box covers. A place narrows what you get back. It never opens data outside your coverage areas. A statewide dataset opens only when your coverage has a county in its state, and a national one opens with any coverage.

​
Topics

A topic is the subject a dataset is filed under. Topics come from one fixed list, such as parcels-property, zoning-land-use or development-activity (permits, plans and inspections). topics list returns the list with a title and description for each. Each dataset has one primary topic, and every call that filters by topic uses it. datasets search looks through titles, descriptions, columns, sample values and the text of documents, and ranks what matches. It takes one to four phrasings of what you want, so “building permits” and “construction permits issued” can be tried at once.
  • place limits the search to a place. Left out, it searches your whole coverage.
  • topics limits it to a list of topics, such as ["zoning-land-use"].
  • kinds limits it to a list of kinds of dataset, from layer, table, document, scanned_map and collection.
  • limit is how many matches to return: 12 unless you say, at most 30.
Each match names its datasetId, kind, title, place and topic, and whether it is locked. A dataset outside your coverage areas, or not included in your plan, comes back locked, and reading it answers outside_coverage or locked. See Coverage, plan and credits. The reply also counts matches elsewhere, so you know whether widening the place would help.

​
Browse everything in a place

datasets list (GET /v1/datasets) returns every dataset of every kind in a place, unranked and without a query. With no place, it lists your whole coverage.
  • It takes the same kinds and topics to narrow it.
  • It answers 25 at a time, and at most 100 a page. Pass the reply’s nextOffset as offset for the next page.
  • Each row names its datasetId and kind.
  • Locked datasets are left out unless you pass includeLocked (--include-locked, or include_locked=True in Python).

​
Know a dataset before you read it

  • datasets get describes a dataset: its columns and their types, its id column, and whether its records have shapes. Read it before writing a condition, so you use real column names.
  • datasets values lists the codes a coded column takes, such as land use or flood zone codes, with their meanings when the source publishes them. Without a published list it returns the 50 commonest values.
  • datasets profile shows, for up to 20 columns, how many rows hold a value, how many distinct values there are, and the smallest and largest.
  • datasets provenance says where a dataset comes from: the public body that publishes it, the sources Ploti read, how values were derived and checked, and any known gaps.
A dataset id is a string such as orange-parcels or ds_orange_fl_building_permits. Don’t parse it or build one yourself: use it exactly as a search returns it. Every call that reads a dataset takes it as dataset, and every reply names it as datasetId. The ids on these pages are examples.