Regrid API v1 Endpoints
lat-lon (reverse geocoding)
We recommend using lat-lon search if possible. Because parcels may span several addresses, using a third-party geocoder (eg Mapbox Places) to identify a point for an address and then searching for the parcel at that point can be more accurate than direct Parcel API address search.
HTTP API request general form
GET /api/v1/search.json?lat=<y>&lon=<x>&token=<token>
Query parameters
token
: Your Regrid assigned authorization token.lat
: Latitude (y-coord) in decimal degrees, WGS84 (EPSG 4326) projection.lon
: Longitude (x-coord) in decimal degrees, WGS84 (EPSG 4326) projection.
To return all parcels in a radius of a point:
radius
(optional, default: 50, Maximum: 32000): Give a radius in meters for which all Parcel Records will be returned if they are within a definable radius from the lat-lon point. No need to include the 'm' for meters, just the integer value between0
and32000
.limit
(optional): Maximum number of Parcel Records to return.return_custom
(optional):true
/false
. Defaulttrue
: A false value omits county-specific fields, making the response contain standard schema fields only.
Result fields
results
: An array of GeoJSON Features each containing the matched Parcel Records. An empty results set with no error means no Parcel Records could be matched. Parcel attributes that have a null value are omitted from the results.
Example API request
GET https://app.regrid.com/api/v1/search.json?lat=42.36511&lon=-83.073107&radius=250&token=<token>
Example results:
Address search
This endpoint allows you to search for parcels by specifying an address as a query string.
HTTP API request general form
GET /api/v1/search.json?query=<address>&context=<path>&token=<token>
Query parameters
token
: Your Regrid assigned authorization token.query
: The URL Encoded address to look up.context
(optional): See notes on context parameter above.limit
(optional, default: 20): Maximum number of Parcel Records to return.strict
(optional): Setstrict=1
to only return Parcel Records in thecontext
.return_custom
(optional):true
/false
. Defaulttrue
: A false value omits county-specific fields, making the response contain standard schema fields only.
Response fields
results
: An array of GeoJSON Features sorted by descending relevance rank containing the matched Parcel Records. An empty results set with no error means no Parcel Records could be matched. Parcel attributes that have a null value are omitted from the results.
Example request
GET https://app.regrid.com/api/v1/search.json?query=440%20burroughs&context=/us/mi/wayne/detroit&strict=1&limit=15&token=<token>
Example results:
Assessor parcel number search
Parcel Id queries return the Parcel Record whose assessor-assigned Parcel Id (also known as Parcel Identification Number (PIN) or Assessor's Parcel Number (APN)) matches the given parameter.
HTTP API request general form
GET /api/v1/search.json?parcelnumb=<pin>&token=<token>
Query parameters
token
: Your Regrid assigned authorization token.parcelnumb
: The assessor's parcel number to look up. Non-alphanumeric characters will be removed when searching.context
(optional): See notes on context parameter above.limit
(optional, default: 20): Maximum number of Parcel Records to return.strict
(optional): Setstrict=1
to only return Parcel Records in thecontext
.return_custom
(optional):true
/false
. Defaulttrue
: A false value omits county-specific fields, making the response contain standard schema fields only.
Response fields
results
: An array of GeoJSON Features sorted by descending relevance rank containing the matched Parcel Records. An empty results set with no error means no Parcel Records could be matched. Parcel attributes that have a null value are omitted from the results.
Example request
GET https://app.regrid.com/api/v1/search.json?parcelnumb=02001069-71&context=/us/mi/wayne/detroit&strict=1&limit=15&token=<token>
Example results:
Polygon search
HTTP API request
POST or GET /api/v1/area.json
Query parameters
token
: Your Regrid assigned authorization token.geojson
: The polygon's GeoJSON geometry (the area being searched), the polygon can not be larger than80
sq miles.limit
: (optional, default:20
, Maximum:1000
) Limits the number of Parcel Records returned perpage
of results.page
: (optional, default:1
) Specifies which 'page' of results to return. A polygon based search may find several thousand parcels, the API divides them up into 'pages' based on thelimit
value set. You must request each page individually,page
1 is returned by default.count
: (optional) When set totrue
the request will only return the total count of parcels within the area, not the Parcel Records themselves.return_custom
(optional):true
/false
. Defaulttrue
: A false value omits county-specific fields, making the response contain standard schema fields only.
Response fields
results
: An array of GeoJSON Features containing the found Parcel Records. An empty results set with no error means no Parcel Records could be found. Parcel attributes that have a null value are omitted from the results.count
: Total number of parcels within the polygon.area
: Total area of the searched polygon (inacres
,sq_meters
, andsq_miles
).status
: Whether the request succeeded or failed.
Example request
POST /api/v1/area.json
Example response:
Owner name field search
Currently the process only matches based on the start of the name string.
For example, if you are looking for a parcel owned by "Jones, Festus", you can search by 'jon', 'jone', 'jones', etc. Searching for 'fest', 'festus', or etc. will not match the parcel.
HTTP API request general form
GET /api/v1/search.json?owner=<name>&context=<path>&token=<token>
Query parameters
token
: Your Regrid assigned authorization token.owner
: The owner name in "Last, First" format. Matches by prefix, you can pass just a last name to get any name beginning with that string. (Case insensitive, minimum 4 characters)context
(optional): See notes on context parameter above.limit
(optional, default: 20): Maximum number of Parcel Records to return.strict
(optional): Setstrict=1
to only return Parcel Records in thecontext
.return_custom
(optional):true
/false
. Defaulttrue
: A false value omits county-specific fields, making the response contain standard schema fields only.
Response fields
results
: An array of GeoJSON Features sorted by descending relevance rank containing the matched Parcel Records. An empty results set with no error means no Parcel Records could be matched. Parcel attributes that have a null value are omitted from the results.
Example API request
GET https://app.regrid.com/api/v1/search.json?owner=techone%20development&context=/us/mi/wayne/detroit&strict=1&limit=15&token=<token>
Example results:
Query by additional parcel data fields
Our parcel API is also queryable at a nationwide level by the following fields:
Field | Description |
---|---|
ll_gisacre | numeric / double precision |
ll_gissqft | numeric / integer |
usps_vacancy | text |
rdi | text |
ll_bldg_count | numeric / integer |
saleprice | numeric / double precision |
zoning | text |
lbcs_activity | numeric |
lbcs_function | numeric |
lbcs_structure | numeric |
lbcs_site | numeric |
lbcs_ownership | numeric |
saledate | date |
szip | text |
ll_uuid | uuid |
landval | numeric |
geoid | text |
owner | text |
parcelnumb | text |
state2 | text |
path | text |
county | text |
yearbuilt | numeric / integer |
improvval | numeric / double precision |
alt_parcelnumb1 | text |
census_block | text |
census_blockgroup | text |
census_tract | text |
census_school_district | text |
qoz | text |
Example queries with supported keys and value formats
GET or POST /api/v1/query?fields[:field_name][:operator]=:value...&token=:token_value
Example API requests
Numeric field ll_gisacre
https://app.regrid.com/api/v1/query?fields[ll_gisacre][eq]=1000.2426&offset_id=1234&limit=5
https://app.regrid.com/api/v1/query?fields[ll_gisacre][ne]=100&fields[ll_gisacre][gt]=99.0&fields[ll_gisacre][lt]=200&fields[ll_gisacre][between]=[100, 300]
Text field zoning
https://app.regrid.com/api/v1/query?fields[zoning][ilike]=RS-1&fields[zoning][ne]=RS-1&fields[zoning][between]=["RS-1", "RS-14"]&fields[zoning][nin]=["RS-1", "RS-9", "MHPD", "RD-D", "AG-2"]&fields[zoning][order]=DESC
Date field saledate
https://app.regrid.com/api/v1/query?&fields[saledate][between]=["2020", "2021/04/22"]&fields[saledate][isnull]=false&limit=100
Boolean field struct
https://app.regrid.com/api/v1/query?fields[struct][ne]=false&fields[struct][eq]=true&fields[struct][isnull]=false
Example results format
Supported types and query parameters
All field types are supported. The operators available vary by field type:
Field Type | Operators |
---|---|
Number | eq, ne, isnull, between, gt, gte, lt, lte, in, nin, order |
Text | eq, ne, isnull, in, nin, ilike |
Date | eq, ne, isnull, between, gt, gte, lt, lte, in, nin, order |
Boolean | eq, ne, isnull |
All Types | limit, count, offset_id |
Operators on each field
fields[:field_name][:operator]
Operator | Description |
---|---|
eq | equal |
ne | not equal |
isnull | is null, takes boolean true/false values only |
between | between inclusive |
gt | greater than |
gte | greater than or equal |
lt | less than |
lte | less than or equal |
in | in set |
nin | not in set |
ilike | case insensitive, matches the given string within the text field value (ex %VALUE%) |
order | ASC/DESC |
Parameters for the entire query
:param_name=:value
Parameter | Description |
---|---|
count | true/false |
offset_id | See Pagination for details |
limit | An integer (API-wide max limit is 1000, default is 20) |
return_geometry | true/false. Default true |
return_custom | true/false. Default true: A false value omits county-specific fields, making the response contain standard schema fields only. |
return_field_labels | true/false. Default true |
context | A path string as described here |
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 id
from a previous query. Each parcel record has an id
for location in our database. You will need the id
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 id
is located at the root level of each parcel feature returned with id
key.
Example pagination first request
Give me the parcel records in Los Angeles County where the parcel acreage is greater than 2 acres. For reference, there are 228,122 parcels matching this query.
https://app.regrid.com/api/v1/query?fields[geoid][eq]=06037&fields[ll_gisacre][gt]=2&offset_id=0&limit=1000
Example pagination subsequent request
https://app.regrid.com/api/v1/query?fields[geoid][eq]=06037&fields[ll_gisacre][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 count=true
. Otherwise, successive pages can be requested until the results are less than the limit or empty.
Count
When the 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 count
return an integer value in the following format.
Example results format
Limit is ignored when the count
operator is present.
Customize response payload
To reduce payload size there are a several flags available. These parameters default to true
.
A false
on each of these parameters will yield the following results:
return_geometry
: A list of features is returned without geometry values.return_custom
: County-specific custom fields are not included in results. This can be used to retrieve only Standard Schema results.return_field_labels
: An object of Standard Schema field names and descriptions are not returned within each feature.
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
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
AND
ed together. - Boolean and boolean-like fields (struct, usps_vacancy, rdi) can only be queried with a subset of operators (eq, ne, isnull).
Find by ll_uuid
This endpoint allows you to lookup a parcel record by our universal unique id - ll_uuid as described in our parcel schema.
HTTP API request general form
GET /api/v1/parcel/<ll_uuid>.json?token=<token>
Query parameters
ll_uuid
: The UUID retrieved from another Regrid API calltoken
: Your Regrid assigned authorization tokenreturn_custom
(optional):true
/false
. Defaulttrue
: A false value omits county-specific fields, making the response contain standard schema fields only.
Example API request
GET https://app.regrid.com/api/v1/parcel/16bc4f67-009a-496c-bd0a-9e9d55f5228b.json?token=<token>
Example results:
Parcel record search by using the parcel path
Endpoint used to get individual parcel records returned as a GeoJSON feature by sending a parcel path.
HTTP API request general form
GET /api/v1/parcel.json?path=<path>&token=<token>
Query parameters
-
path
: The canonical path of the parcel in the Regrid system. For example,/us/mi/wayne/detroit/555
. Response fields A single GeoJSON Feature for the requested parcel (rather than an array of results). Parcel attributes that have a null value are omitted from the results. token
: Your Regrid assigned authorization token.return_custom
(optional):true
/false
. Defaulttrue
: A false value omits county-specific fields, making the response contain standard schema fields only.
Example request
GET https://app.regrid.com/api/v1/parcel.json?path=/us/mi/wayne/detroit/364491&token=<token>
Example truncated results
Response format
On success, all of the above requests return one or an array of GeoJSON Features representing the matched parcels. These Features include polygon geometries and properties
. Our standard fields are documented in the Regrid Parcel Schema. Some additional undocumented fields may be included in the properties
. An empty results set with no error means no parcels could be matched. Parcel attributes that have a null value are omitted from the results.
Example response payload with results:
Notes on parcel properties
headline
: a human-friendly display address for the parcel. If no address is available, it falls back to the parcel number.path
: The parcel's unique identifier as described above in "Parcel Paths Above"fields
: Columns from the parcel table. These include standard column names wherever fields are available, plus additional columns varying by the particular county & data available. Parcel attributes that have a null value are omitted from the results.field_labels
: Human-friendly labels for each key infields
.context
: A bit of info about the city or county where this parcel is found, including apath
one can use ascontext
for further searches.
Regrid Parcel Record Schema endpoint
Endpoint used to fetch the current Regrid Parcel Schema.
HTTP API request
GET /api/v1/schema.json
Response fields
A hash with details on all fields in the Regrid Parcel Schema
Example response:
Parcels + Matched Building Footprints
Requests
If you have chosen our Regrid Parcel Data + Matched Building Footprints API, then by default any of the above Parcel API endpoints will also return building data. This can be controlled with the following parameter:
matched_buildings
: Set tofalse
to disable building footprint data in the response. Default istrue
when the account supports it.
Response format
In the standard response format, results
is an array of parcel GeoJSON features. When
matched building footprint data is also returned, there will be an additional top-level buildings
array of GeoJSON Features. Each Feature in the buildings
array will be a building record.
- See the Buildings Schema document for descriptions of the
properties
of each building GeoJSON Feature. - Each building has one or more
ll_uuids
listed in its properties. These specify which of the parcels contain or overlap these building footprints and correspond to thell_uuid
field in each of the parcelresults
.
An example response is below, with coordinates and parcel fields removed for brevity:
Example response:
Parcels + Matched Secondary Addresses
Requests
If your account has Matched Secondary Addresses enabled, then by default any of the Parcel API endpoints will include these addresses. You can select this per-call with the following query parameter:
matched_addresses
: Set tofalse
to disable matched addresses data in the response. Default istrue
when the account supports it.
Response format
In the standard response format, results
is an array of parcel GeoJSON features.
The secondary addresses will appear in a parcel feature's properties.addresses
array.
- See the Matched Address Schema document for a list of each field and descriptions.
A sample response, with some fields abbreviated for brevity:
Parcels + Enhanced Ownership
Requests
If your account has Enhanced Ownership enabled, then by default any of the Parcel API endpoints will include this extra ownership data. You can select this per-call with the following query parameter:
enhanced_ownership
: Set tofalse
to disable enhanced ownership data in the response. Default istrue
when the account supports it.
Response format
In the standard response format, results
is an array of parcel GeoJSON features.
The enhanced ownership will appear in a parcel feature's properties.enhanced_ownership
array.
- See the Enhanced Ownership Schema document for a list of each field and description.
A sample response, with some fields abbreviated for brevity:
County metadata (verse) endpoint
This endpoint allows you to retrieve all records from our verse table as described in our verse schema. These records are primarily counties in the United States with some cities when that is how data is reported.
The response is formatted as a list of GeoJSON features as shown in sample results below.
Note for bulk data customers
This endpoint may reflect data updates before they are available in bulk files. The verse file included with your bulk data deliveries will always reflect the current state of data available to you.
HTTP API request general form
GET /api/v1/verse.json
Query parameters
with_geometry
: Geometry (simplified county shape) will not be returned by default unless this field is included with atrue
value.
Example API request
GET https://app.regrid.com/api/v1/verse.json?with_geometry=true
Example results
Typeahead API
We offer an autocomplete/typeahead endpoint to complete and search addresses. Please see the Typeahead API documentation for details about this feature, and contact our sales team at parcels@regrid.com for a demo or to enable your account.
API Account Usage Stats endpoint
Used to check your current API usage stats to see how many requests, parcel records, and tiles have been used during this monthly cycle. You can also set an optional parameter to see your full usage history.
HTTP API request general form
GET /api/v1/usage.json?token=<token>
Query parameters
token
: Your Regrid assigned authorization token.full_history
(optional): Set totrue
if you would like API usage history that goes beyond your current monthly cycle.return_by_token
: (optional) returns usage by all available tokens. Seeby_token
array in response of each token's usage data.return_by_this_token
: (optional) returns usage for only this token.
Response fields
cycle_dates
: The start and end date of the current cycle.cycle_usage
: Counts ofrequests
,results
, andtiles
used during the current cycle.full_history
: An array of stats for previous cycles. Only included if the optionalfull_history
boolean query parameter is set totrue
.by_token
: An array of usage data by each token. Keys include token 'name', 'token_fragment' the last few characters of the token, 'cycle_usage' object and 'full_history' array.status
: Whether the request succeeded or failed.
Example request:
GET https://app.regrid.com/api/v1/usage.json?token=<token>&full_history=true
Example response:
Reporting Data Issues to Regrid
This is an alpha endpoint and may change before release
You can report issues with specific parcels or general areas to us using this report endpoint. Reports help us prioritize updates. However, we cannot apply data received to this endpoint directly to our parcel data or respond individually to specific reports.
HTTP API request general form
POST /api/v1/report.json?token=<token>
Query parameters
token
: Your Regrid assigned authorization token.path
: A path to a specific parcel or placell_uuid
(optional): The ll_uuid of a parcel, if the report is for a specific parcelcomment
(optional): String describing the issuedetails
(optional): A hash with details on specific fields. This hash only accepts standard column names as keys.
Response fields
status
: Whether the request succeeded or failed.message
: Message on the status of the report.id
: ID of the new report.
Example request
POST https://app.regrid.com/api/v1/report.json?token=YOUR_TOKEN_HERE
Example response
Platform / Library Specific Notes
Shapely
To create a shapely shape in Python from the array of coordinates that come as part of the GeoJSON response from the API, the coordinates list can not be passed into a MultiPolygon or Polygon constructor or it may return an error.
Instead try import shape from shapely.geometry
and pass in the geojson response to that. The shapely library might have issues instantiating shapes from a list of coordinates versus directly from a geojson the other ways.
In this section
- lat-lon (reverse geocoding)
- Address search
- Assessor parcel number search
- Polygon search
- Owner name field search
- Query by additional parcel data fields
- Find by ll_uuid
- Parcel record search by using the parcel path
- Response format
- Regrid Parcel Record Schema endpoint
- Parcels + Matched Building Footprints
- Parcels + Matched Secondary Addresses
- Parcels + Enhanced Ownership
- County metadata (verse) endpoint
- Typeahead API
- API Account Usage Stats endpoint
- Reporting Data Issues to Regrid
- Platform / Library Specific Notes