To support large requests that can take some time to process, we have a set of endpoints for their creation, management and download when they are ready.
When using the the API v2 Parcel Points endpoint with a list of points that exceed our limit of 1000, the batch processing system can be used. It supports up to 100,000 input points per request.
Another key feature our batch processing includes is allowing a custom identifier defined by API users on each point (using the custom_id key). This allows one to keep track of their input point to easily verify if that point found a parcel (or parcels!) or not.
Input can be a CSV file, CSV data or like our full real-time API v2 a GeoJSON Feature Collection of Points.
Output is the same as our [API v2 response format](link to v2 IO output section] but file size can be significantly larger.
To fine tune your requests Regrid's Batch Parcel API supports the relevant parameters of API v2 endpoints.
We have introduced an optional callback_url parameter if you'd like to be informed programatically when the batch processing job is complete and ready to download. Just have your endpoint ready to receive your callback URL.
The batch points endpoint also supports an optional country ID to be used with Canada parcels as well. [Link to update to add Canada to plan]
Parcel counts are incremented when the completed job has been downloaded.
Batch Endpoints at a glance
https://app.regrid.com/api/v2/[country_code]/...
batch/pointsbatch/status/<job_uuid>batch/jobsbatch/<job_uuid>/download-
batch/<job_uuid>Delete
Batch Endpoints in detail
batch/points
Reverse Geocoding endpoint
api/v2/batch/points
Similar to the API v2 parcels/point endpoint. This endpoint receives a list of points in two forms: A standard CSV file upload, or the API v2 standard GeoJSON format containing a Feature Collection of Point Features. One can also include a custom_id value to track whether each point has a parcel match in the results. This custom ID does not have to be unique. Letters and numbers are allowed.
Filtering params are similar to the parcels/point endpoint as listed below.
The optional callback_url parameter is used to programatically be informed when the batch processing job is complete and ready to download.
HTTP API request general form
POST /api/v2/batch/points?callback_url=<your domain called when ready to download>&token=<token>
Query parameters
-
geojson: A GeoJSON Feature Collection containing GeoJSON Point Features. Optionally, the POST body can also contain a direct GeoJSON Feature Collection object at the root level, without being scoped within a 'geojson' object. The properties can also contain acustom_idkey to identify returned parcels to each point. -
file: A CSV file with a header column containinglat,lon,custom_id(optional) columns. - CSV text in request body: Raw CSV text can also be posted directly in the request body.
-
callback_url: Optional webhook to notify when the job is complete (tries up to 3 times). Payload sent to the callback URL is the same as the batch status endpoint. [anchor link to that] -
token: Your Regrid authorization token. -
return_geometry: Default true. Features are returned without geometry values. This reduces the payload size significantly if only field data is required. Default false -
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. -
return_stacked: Default true: A false value returns the first parcel if geometries are identical. When stacked parcels are found from a given point, each parcel is returned with thecustom_idappended to the parcel Feature result's properties object. -
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.
Example US API request
POST https://app.regrid.com/api/v2/us/batch/points?&token=<token>
Body:
{
"geojson": {
"type": "FeatureCollection",
"features": [
{
"type": "Feature",
"properties": {
"custom_id": "700111a1-4a9a-4e36-83e2-1d0933a5f485"
},
"geometry": {
"type": "Point",
"coordinates": [
-84.280105,
46.517196
]
}
},
{
"type": "Feature",
"properties": {
"custom_id": "second custom id"
},
"geometry": {
"type": "Point",
"coordinates": [
-84.344674,
46.52742
]
}
}
]
}
}
CSV text body:
"lat","lon","custom_id"
44.759405, -83.549250, 22c26ea7-fcb5-4d78-9d3d-821168f9576f
44.803992, -83.751508, 1706929e-ce96-4ef0-bd64-6f8fda76ad57
"29.993991",-95.513315,"17762f92-8f92-4b6e-af30-f61333575cac"
"29.861515",-95.657579,"17753584-2211-4b1d-9b2c-444a59c7a22f"
CSV file:
Header contains
Content-Type: multipart/form-data
body contains
{"csv_file": "[filepath.csv]"}
curl request:
curl --request POST \
--url 'https://app.regrid.come/api/v2/batch/points?token=REGRID_TOKEN&' \
--header 'content-type: multipart/form-data' \
-F "csv_file=@points_file.csv"
Note: If a custom_id is not included on some or all of the input points, the index of the data will be used as the custom_id (starting with "0" through the number of input points).
Remember custom_id values in results will not be unique as multiple parcels matching on a single point may be returned.
Example US results:
{
"message": "Processing 'points' job type",
"job_uuid": "9fa5920e-29ab-49a7-98a9-e781da6385c8",
"status": "queued"
}
batch/<job_uuid>/status
Check current status of running jobs, when status is "ready" the job can be downloaded using the download endpoint.
| key | value |
|---|---|
job_type |
Type of job being run |
job_uuid |
Unique identifier for the job |
status |
Current status of the job ('queued', 'running', 'ready', 'downloaded', 'removed', 'failed') |
updated_at |
UTC timestamp of last updated |
percent_complete |
Percentage complete of the job based on the input count |
processed_count |
Number of input points that have been processed |
failed_count |
Number of failures that have occurred during processing job (not a number of point in error) |
time_remaining |
Estimated seconds remaining for the job to complete |
HTTP API request general form
GET /api/v2/batch/<job_uuid>/status&token=<token>
Query parameters
-
token: Your Regrid authorization token.
URL parameter
-
job_uuid: (required) The UUID returned by the initial batch call and available in the status list endpoint. For example, 8b6f4f51-58ad-4969-93b3-fdfb348a7084.
Response fields
-
job: Contains an object with metadata about the current job including:status,job_uuid,percent_complete
Example US API request
POST https://app.regrid.com/api/v2/batch/status/939ed5d2-ec3b-479a-9dc6-a06360f97f70?token=<token>
Example US results:
{
"job": {
"job_type": "points",
"job_uuid": "939ed5d2-ec3b-479a-9dc6-a06360f97f70",
"status": "ready",
"updated_at": "2025-02-28T10:00:27.102-05:00",
"percent_complete": 100.0,
"processed_count": 9,
"failed_count": 0,
"time_remaining": 0
}
}
batch/jobs
Check current status of all running jobs. Note order is by most recently completed 'ready' jobs. All jobs attached to your account are listed here. Removed jobs won't be listed here.
api/v2/batch/jobs
HTTP API request general form
GET /api/v2/batch/jobs?token=<token>
Query parameters
-
token: Your Regrid authorization token. -
return_all: Default false. By default the most recently updated 10 jobs will be returned from the past 31 days. If set to true, all jobs will be returned including those that have been removed.
Response fields
-
jobs: Contains an array of each job's status
Example US API request
GET https://app.regrid.com/api/v2/batch/jobs?token=<token>
Example US results:
{
"jobs": [
{
"job_type": "points",
"job_uuid": "10e0a07f-f73e-4691-8292-598d087af69e",
"status": "ready",
"updated_at": "2025-02-28T06:08:51.849-05:00",
"percent_complete": 100.0,
"processed_count": 102,
"failed_count": 0,
"time_remaining": 0
},
{
"job_type": "points",
"job_uuid": "9fa5920e-29ab-49a7-98a9-e781da6385c8",
"status": "downloaded",
"updated_at": "2025-02-28T06:07:56.494-05:00",
"percent_complete": 100.0,
"processed_count": 102,
"failed_count": 0,
"time_remaining": 0
},
{
"job_type": "points",
"job_uuid": "902e5b7f-37a9-462b-925a-fd2b62b63de7",
"status": "running",
"updated_at": "2025-02-25T13:51:13.945-05:00",
"percent_complete": 20.0,
"processed_count": 20,
"failed_count": 0,
"time_remaining": 50
}
]
}
batch/<job_uuid>/download
Download the job when ready. The result is formatted as Newline-delimited GeoJSON (each parcel is represented by a GeoJSON feature on a separate newline). This GeoJSON standard format allows for easily streaming and processing results as they are being downloaded.
Parcel counts are incremented when the completed job has started a download. Input points that don't return parcels and stacked parcels are included in counts. So the total parcel count will be at least of input parcels.
api/v2/batch/<job_uuid>/download
HTTP API request general form
GET /api/v2/batch/<job_uuid>/download?token=<token>
Query parameters
-
token: Your Regrid authorization token.
URL parameter
-
job_uuid: (required) The UUID returned by the initial batch call and available in the status list endpoint. For example, 8b6f4f51-58ad-4969-93b3-fdfb348a7084.
Response fields
- GeoJSON Features on separate line, each containing matched parcel records. An empty Feature means there was no match for the given point.
Example US API request
GET https://app.regrid.com/api/v2/batch/939ed5d2-ec3b-479a-9dc6-a06360f97f70/download?token=<token>
Example US results:
{ "type": "Feature", "geometry": { "type": "Polygon", "coordinates": [ [ [ -83.0734727315047, 42.3651818518358 ], [ -83.0732453652113, 42.3647767765094 ], [ -83.0725988503963, 42.364985221084 ], [ -83.0728299168503, 42.3653894282331 ], [ -83.0733713700996, 42.3652143873895 ], [ -83.0734727315047, 42.3651818518358 ] ] ] }, "properties": { "headline": "440 Burroughs St", "path": "/us/mi/wayne/detroit/364491", "fields": { "ogc_fid": 364491, "geoid": "26163", "parcelnumb": "02001069-71", "parcelnumb_no_formatting": "0200106971", "usecode": "22320", "usedesc": "OFFICE BLDG-3 STORIES OR MORE", "zoning": "SD2", "zoning_description": "Special Development District Mixed Use", "struct": true, "structno": 1, "yearbuilt": 1926, "structstyle": "Office Buildings", "parvaltype": "ASSESSED", "parval": 0.0, "saleprice": 0.0, "owner": "TECHONE DEVELOPMENT LLC", "mailadd": "440 BURROUGHS", "mail_city": "DETROIT", "mail_state2": "MI", "mail_zip": "48202", "address": "440 BURROUGHS ST", "homestead_exemption": "0", "ll_address_count": 44, "ll_bldg_footprint_sqft": 28713, "ll_bldg_count": 1, "dpv_status": "V", "dpv_codes": "DNNNY", "dpv_notes": "AAN105", "dpv_type": "H", "cass_errorno": "12.2,14.7,15.1,A1", "rdi": "N", "usps_vacancy": "N", "usps_vacancy_date": "2024-01-04", "lbcs_activity": 2300.0, "lbcs_activity_desc": "Office", "lbcs_structure": 2100.0, "lbcs_structure_desc": "Office or bank building", "lbcs_site": 6000.0, "lbcs_site_desc": "Developed site with buildings", "fema_flood_zone": "X", "fema_flood_zone_subtype": "AREA OF MINIMAL FLOOD HAZARD", "fema_flood_zone_raw": "[{\"zone\":\"X\",\"subtype\":\"AREA OF MINIMAL FLOOD HAZARD\",\"percent\":100}]", "fema_flood_zone_data_date": "2023-10-17", "census_unified_school_district": "Detroit Public Schools Community District", "zoning_type": "Planned", "zoning_subtype": "Planned", "zoning_code_link": "https://www.zoneomics.com/code/detroit-MI/chapter_11/#SD2", "zoning_id": "10070643", "saddno": "440", "saddstr": "BURROUGHS", "saddsttyp": "ST", "scity": "DETROIT", "original_address": "{\"address\":\"440 BURROUGHS\",\"szip\":\" \"}", "city": "detroit", "county": "wayne", "state2": "MI", "szip": "48202-3429", "szip5": "48202", "address_source": "county,census_places;cass", "legaldesc": "N BURROUGHS 10-11 BLK 12--CASS FARM CO LTD SUB L19 P35 PLATS, W C R 2/27 37-38 & S 1/2 OF VAC ALLEY ADJ MANDLEBAUMS SUB L2 P8 PLATS, W C R 2/62 189.53 IRREG", "lat": "42.365083", "lon": "-83.073037", "qoz": "Yes", "qoz_tract": "26163518900", "census_tract": "26163533900", "census_block": "261635339004021", "census_blockgroup": "261635339004", "census_zcta": "48202", "ll_last_refresh": "2023-01-31", "recrdareano": 142125, "gisacre": 0.697, "sqft": 30365.0, "ll_gisacre": 0.69741, "ll_gissqft": 30380, "path": "/us/mi/wayne/detroit/364491", "ll_stable_id": "preserved", "ll_uuid": "16bc4f67-009a-496c-bd0a-9e9d55f5228b", "ll_updated_at": "2024-02-06 13:03:55 -0500", "ll_zoning_backup": "SD2", "ll_zoning_description_backup": "Special Development District Mixed Use" }, "context": { "headline": "Detroit, MI", "name": "Detroit, MI", "path": "/us/mi/wayne/detroit", "active": true }, "custom_id": "point of interest", "ll_uuid": "16bc4f67-009a-496c-bd0a-9e9d55f5228b" }, "id": 364491 }
{ "type": "Feature", "geometry": null, "properties": { "ll_uuid": null, "custom_id": "your custom id" } }
batch/<job_uuid> Delete
Delete the job. Jobs will be automatically deleted after 30 days from creation date. At any time jobs can be deleted. Deletion removes stored input points & parameters, any download files that may have been created, and the optional callback URL.
api/v2/batch/<job_uuid>
HTTP API request general form
DELETE /api/v2/batch/<job_uuid>?token=<token>
Query parameters
-
token: Your Regrid authorization token.
URL parameter
-
job_uuid: (required) The UUID returned by the initial batch call and available in the status list endpoint. For example, 8b6f4f51-58ad-4969-93b3-fdfb348a7084.
Example US API request
DELETE https://app.regrid.com/api/v2/batch/939ed5d2-ec3b-479a-9dc6-a06360f97f70?token=<token>
Example US results:
{
"message": "Job removed"
}
Batch Best Practices and Limits
- Each batch job can contain up to 100,000 points with a maximum upload size of 50MB. If you need to process more data, consider breaking it into multiple batches.
- Input data needs to contain at least 'lat', 'lon' and optional 'custom_id' CSV fields (i.e. columns or GeoJSON properties). If your source data has additional fields they will be ignored. If running into the input file limit, one can send only the required columns.
- If response payload size needs to be minimized, try disabling returned geometries with the parameter flag upon job creation,
return_geometry=false, and/or if stacked parcels aren't needed, try disabling them withreturn_stacked=false. - If points aren't on exact parcels like off roads, or bodies of water, try using a radius.
- If you have a very large number of points to identify, try out your query parameters with a few points here, or using the API v2 Points endpoint `api/v2/parcels/points, before running the full sized batch job.
Comments
0 comments
Please sign in to leave a comment.