Documentation menu
API

Pagination

Paginate, sort and filter lists, such as the counties in a state.

Lists return one page at a time. Filter with the list’s parameters, order with sort, and use next_cursor to get the next page.

Paginate a list

  1. 1

    Request the first page

    Set size, and add total=true if you want a count:
    Terminal
    curl -G 'https://api.placestack.com/v1/jurisdiction' \
      --data-urlencode 'state=MI' \
      --data-urlencode 'tier=subregion' \
      --data-urlencode 'size=2' \
      --data-urlencode 'total=true' \
      -H "Authorization: Bearer $PLACESTACK_API_KEY"
  2. 2

    Read the list

    Items are in data. The other fields describe the page:
    JSON
    {
      "object": "list",
      "data": [ ... ],
      "has_more": true,
      "next_cursor": "eyJ2IjoyLCJzIjoibmFtZSIsImsiOiJBbGdlciBDb3VudHkiLCJ0Ijoi...",
      "suppressed": 0,
      "total": { "value": 83, "relation": "eq" }
    }
  3. 3

    Request the next page

    Send the same request with cursor set to next_cursor. Repeat until has_more is false.
    Terminal
    curl -G 'https://api.placestack.com/v1/jurisdiction' \
      --data-urlencode 'state=MI' \
      --data-urlencode 'tier=subregion' \
      --data-urlencode 'size=2' \
      --data-urlencode 'cursor=eyJ2Ijoy...' \
      -H "Authorization: Bearer $PLACESTACK_API_KEY"
sizeHow many items per page, from 1 to 200. Defaults to 20.
cursorThe next_cursor from the previous page. Leave it out for the first page.
totalSet to true on the first page to get a count of every match. It's ignored on later pages.

Sorting

Set sort to a field, with a leading - for descending, and send the same sort on every page. Each list’s reference names its sort fields. Any other field returns field_unknown.

Terminal
curl -G 'https://api.placestack.com/v1/parcel' \
  --data-urlencode 'fips=37183' \
  --data-urlencode 'min_acres=5' \
  --data-urlencode 'sort=-market_value' \
  -H "Authorization: Bearer $PLACESTACK_API_KEY"

Results for address or owner are ordered by match quality and can’t be sorted. Jurisdiction lists are ordered by tier, largest first, then by name.

Filtering

Each list’s reference names its filters. Repeat a parameter to match any of its values. For a range, use min_ and max_, together or alone. This finds parcels of 5 to 50 acres in two North Carolina counties:

Terminal
curl -G 'https://api.placestack.com/v1/parcel' \
  --data-urlencode 'fips=37183' \
  --data-urlencode 'fips=37135' \
  --data-urlencode 'min_acres=5' \
  --data-urlencode 'max_acres=50' \
  -H "Authorization: Bearer $PLACESTACK_API_KEY"

Items with no value for a range field are excluded. For example, a parcel with no area is excluded by min_acres.

List object

objectAlways list.
dataThe items on this page. Each item's object field names its type.
has_moreWhether another page follows this one.
next_cursorPass it as cursor to get the next page. It's null on the last page.
suppressedThe number of matches not returned because of your plan or the data license. If above 0, check what your plan includes.
totalPresent only on the first page with total=true. relation is eq when value is exact, or gte when value is a lower bound.

Errors

An invalid parameter, sort or cursor returns 422:

parameter_invalidA parameter value is not valid. field names the parameter.
field_unknownThe list can't be sorted by that field. detail lists the supported fields.
cursor_expiredStart the list again without a cursor.
cursor_sort_mismatchSend the sort the cursor was issued for, or start again without a cursor.

Next steps

Endpoints

Every endpoint, by group.

Continue