International Query By Field

In addition to the primary identifiers in our dataset, our API is also queryable at a nationwide level using a subset of our 76 international schema fields that have been optimized for queries at scale. The following is the general form for this endpoint. See additional query endpoints in the OpenAPI Spec Sandbox for examples on each field type and our API Examples article. Multiple fields can be used in a single query (up to 4), to refine results.

api/v2/<country code>/parcels/query

Currently our parcel API is also queryable internationally by the following fields:

Supported Countries and their respective country codes (admin0):

Example queries with supported keys and value formats

GET or POST /api/v2/<country code>/query?fields[<field_name>][<operator>]=<value>...&token=<token_value>

Example API requests

Numeric field ll_gissqm

• [https://app.regrid.com/api/v2/ca/query?fields[ll_gissqm](https://app.regrid.com/api/v2/ca/query?fields\[ll_gissqm)][eq]=1000.2426&offset_id=1234&limit=5
• [https://app.regrid.com/api/v2/ca/query?fields[ll_gissqm](https://app.regrid.com/api/v2/ca/query?fields\[ll_gissqm)][ne]=100&fields[ll_gissqm][gt]=99.0&fields[ll_gissqm][lt]=200&fields[ll_gissqm][between]=[100, 300]

Text field reserve

• [https://app.regrid.com/api/v2/ca/query?fields[reserve](https://app.regrid.com/api/v2/ca/query?fields\[reserve)][ilike]=BIG ISLAND INDIAN RESERVE&fields[zoning][ne]=BEARDYS AND OKEMASIS IR 96 AND 97B&fields[reserve][order]=DESC

Example Results Format

{
    "parcels": {
        "type": "FeatureCollection",
        "features": [
          array of GeoJSON features...
        ]
    }
}

Supported types and query parameters

All field types are supported. The operators available vary by field type:

Operators on each field

fields[<field_name>][<operator>]

Parameters for the entire query

• token: Your Regrid authorization token.
• fields[<field_name>][<operator>]: Use a supported field name and operator as the parameter key, and a valid value to filter parcels.
• geojson: A GeoJSON object with at least one geometry to filter results. The geometries can be no larger than 207,000 square meters. If both geojson and lat-lon are present, geojson takes precedence. Accepted GeoJSON formats are: FeatureCollection, Feature or geometry. Supported geometries: Polygon, MultiPolygon, Point, MultiPoint, LineString and MultiLineString. Variations of geometry types are allowed in a FeatureCollection.
• radius: (Default: 0, Maximum: 32000) Radius in meters for which all Parcel records will be returned if they are within the radius zone from latitude and longitude point. See Pagination section for details.
• offset_id: ID from a previous query exceeding the limit, returns the next set of results up to limit.
• limit: (optional) Default 20. Maximum number of Parcel Records to return. Max is 1000.
• path: Represents a full or partial path as defined by the Regrid International Schema ('/admin0/admin1', '/country code/admin1/admin2_slug', or '/country code/admin1/admin2_slug/admin3_slug'), or a full parcel path string (like '/admin0/admin1/admin2_slug/admin3_slug/parcel_path_id')
• return_count: Set to true to enable count of parcels in query.
• return_geometry: Default true. Features are returned without geometry values. This reduces the payload size significantly if only field data is required.
• return_custom: Default false: A true value allows county-specific fields to be passed through beyond standard schema fields only.
• return_field_labels: Default false: A true value shows the naming convention for each standardized schema field.
• return_custom_id: Default false. Set to true when input GeoJSON features include a 'custom_id' field in the 'properties' object. This flag enables the resulting parcels to include the user-set custom ID for matching parcel(s).

International Pagination

If your request returns more than 1000 parcel records, you will need to use pagination for your query results.

Pagination is performed by including an offset_id parameter with the integer ogc_fid from a previous query. Each parcel record has an ogc_fid field in our database. You will need the ogc_fid of the last parcel record from your previous query to use in the next iteration of the pagination request. This request returns the remaining parcels up to the value of the limit parameter.

To page results, the initial request needs to include the parameter offset_id=0 which indicates results need to be in ID order. The required ogc_fid is located at the root level of each parcel feature returned with ogc_fid key.

Note: The ogc_fid values returned are not stable long-term but can be used dymically in pagination requests or scripts that populate these values and use them in followup requests.

Example pagination first request

Give me the parcel records where the parcel size is greater than 200 square meters.

[https://app.regrid.com/api/v2/query?fields[geoid](https://app.regrid.com/api/v2/query?fields\[geoid)][eq]=06037&fields[ll_gissqm][gt]=2&offset_id=0&limit=1000

Example pagination subsequent request

[https://app.regrid.com/api/v2/query?fields[geoid](https://app.regrid.com/api/v2/query?fields\[geoid)][eq]=06037&fields[ll_gissqm][gt]=2&offset_id=155171239&limit=1000

The order parameter is not allowed when paging, as is indicated by an error message if the query is invalid.

If a total count is needed, an initial query can be made with return_count=true. Otherwise, successive pages can be requested until the results are less than the limit or empty.

Count

When the return_count parameter is set to a boolean value of true or false, the results will be the entire dataset filtered by other optional operators on the field(s). When the boolean value is true, there is no cost to return the total number of parcels for the query.

Requests with return_count return an integer value in the following format.

Example results format

 {
    "count": 1846
  }

Limit is ignored when the return_count parameter is present.

Customize response payload

There are several flags available to reduce payload size.

• return_geometry: A list of features is returned with geometry values. Default true.
• return_custom: Used to retrieve only International Schema results. Default false.
• return_field_labels: An object of International Schema field names and descriptions are returned within each feature. Default false.
• return_stacked: A false value means only the first parcel is returned if geometries are identical. Default true.
  Request format

Queries can be made as GET or POST requests. The examples below show the same query being made by both types of request.

GET request example

fields[ll_gisacre][eq]=1000.2426&fields[ll_gisacre][ne]=1000&limit=5

POST request example

{
  "fields": {
    "ll_gisacre": {
      "eq": 1000.2426,
      "ne":  1000
    }
  },
  "limit": 5
}

Other considerations

• Date formats allowed: YYYY/MM/DD or MM/DD/YYYY Also, a value with a year only like "2022" will evaluate as "2022/01/01".
• Multiple operators are ANDed together.
• To filter results by region, the path parameter in the form returned in parcel results can be used in full or partially, path=/ca/on/durham/oshawa.
• If filtering results with 'admin columns' (admin0, admin1, admin2 and/or admin3), for best results use values that are returned in Regrid results and use an exact match, fields[admin2][eq]=Duram.