Lists

Page through, sort and filter a list, such as the counties in a state.

Lists return one page at a time. Filter with the list’s own parameters, order it with sort, and follow next_cursor for the next page.

Page through a list

Request the first page

Set size, and add total=true if you want a count:

curl 'https://api.placestack.com/jurisdiction?state=MI&level=county&size=2&total=true' \
  -H 'Authorization: Bearer $PLACESTACK_API_KEY'

Read the page block

The items are in item, and page says where you are:

{
  "item": [ ... ],
  "page": {
    "size": 2,
    "next_cursor": "eyJ2IjoyLCJzIjoibmFtZSIsImsiOiJBbGdlciBDb3VudHkiLCJ0Ijoi...",
    "suppressed": 0,
    "total": { "value": 83, "relation": "eq" }
  }
}

Request the next page

Send the same request with cursor set to next_cursor. Repeat until next_cursor is null.

curl 'https://api.placestack.com/jurisdiction?state=MI&level=county&size=2&cursor=eyJ2Ijoy...' \
  -H 'Authorization: Bearer $PLACESTACK_API_KEY'

size: How many items per page, from 1 to 200. Defaults to 25.
cursor: The next_cursor from the previous page. Leave it out for the first page.
total: Set 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. Each list’s reference names the fields it sorts on. Send the same sort on every page.

curl 'https://api.placestack.com/jurisdiction?state=MI&level=county&sort=-population' \
  -H 'Authorization: Bearer $PLACESTACK_API_KEY'

Filtering

Filter with the parameters each list names in its reference. Repeat a parameter to match any of its values. For a range on a number or a date, add [gte], [lte], [gt] or [lt] to the name. This finds the counties in Michigan or Ohio with at least 500,000 people:

curl -g 'https://api.placestack.com/jurisdiction?state=MI&state=OH&level=county&population[gte]=500000' \
  -H 'Authorization: Bearer $PLACESTACK_API_KEY'

On lists that take include_unknown, a row whose value for a filtered field is unknown, such as a district whose code sets no height limit, comes back marked filter_outcome: indeterminate. Set include_unknown=false to leave those rows out.

The page block

size: How many items this page holds.
next_cursor: Pass it as cursor to get the next page. It's null on the last page.
suppressed: Matches left out because your plan or the source's terms don't allow them to be returned. When it's above 0, check what your plan includes.
total: Only when you sent total=true. relation is eq when value is exact, or gte when there are more than 10,000 matches and value is a lower bound.

Errors

A parameter, sort or cursor the list can’t use gets a 422:

parameter_invalid: A parameter has a value it doesn't accept. field names it.
field_unknown: The list doesn't sort or filter on that field. detail lists the ones it does.
vocabulary_value_unknown: Use one of the values the parameter accepts.
cursor_expired: Start the list again without a cursor.
cursor_snapshot_gone: Start the list again without a cursor.
cursor_sort_mismatch: Send the sort the cursor was issued for, or start again without a cursor.

Schemas

Every component schema the API publishes.