Batch Processing API

Batch Processing API

The Regrid Batch Processing API is designed for large-scale point lookups that would be impractical to run synchronously through the standard parcel endpoints. Instead of making thousands of individual requests, you submit a single file of coordinates, let Regrid process the job asynchronously, and download the results when ready.

This is the recommended approach when you need to look up parcels for more points than can be handled efficiently in a single real-time request.

Base URL: https://app.regrid.com/api/v2

Required parameter (all endpoints): token — your Regrid API authorization token.

How it works

The batch workflow follows four steps:

1. Submit a CSV or GeoJSON file of lat/lon points to create a batch job
2. Poll the status endpoint until the job status is ready
3. Download the results as newline-delimited GeoJSON (JSONL)
4. Delete the job when you no longer need it (or let it auto-expire after 30 days)

Optionally, provide a callback_url webhook to be notified automatically when your job is complete instead of polling.

Job statuses

Create a Points Batch Job

POST /batch/points

Submits a list of latitude/longitude points for parcel lookup. Works similarly to the parcels/point endpoint but processes the entire list asynchronously as a single job. Accepts up to 100,000 points or 50MB per job.

Input formats

You can submit points in one of two ways:

• CSV file — a file with header columns lat, lon, and optionally custom_id
• GeoJSON — an API v2 standard GeoJSON FeatureCollection of Point Features, optionally including a custom_id in each feature's properties

The custom_id field lets you track which input point matched which parcel in the results. It does not need to be unique.

Query parameters

Example request

POST https://app.regrid.com/api/v2/batch/points?token=<token>&radius=100&return_custom_id=true

CSV file format

lat,lon,custom_id
42.36511,-83.073107,point_001
34.05223,-118.24368,point_002
40.71278,-74.00594,point_003

Example response

{
  "message": "Processing 'points' job type",
  "job_uuid": "9fa5920e-29ab-49a7-98a9-e781da6385c8",
  "status": "queued"
}

Store the job_uuid — you will need it to check status and download results.

Create a Country-Specific Points Batch Job

POST /{country_code}/batch/points

Same as POST /batch/points but scoped to a specific country. Use this when processing points outside the US.

Path parameter

Example request

POST https://app.regrid.com/api/v2/ca/batch/points?token=<token>

All other parameters and behavior are identical to POST /batch/points.

Check Batch Job Status

GET /batch/{job_uuid}/status

Returns the current status and progress of a batch job. Poll this endpoint after submitting a job until the status is ready, at which point you can download the results.

Path parameter

Example request

GET https://app.regrid.com/api/v2/batch/9fa5920e-29ab-49a7-98a9-e781da6385c8/status?token=<token>

Example response

{
  "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,
    "processed_count": 9,
    "failed_count": 0,
    "time_remaining": 0
  }
}

Response fields

List All Batch Jobs

GET /batch/jobs

Returns a list of all batch jobs associated with your token, ordered by most recently updated. By default returns the 10 most recently updated jobs from the past 31 days. Removed jobs are excluded unless return_all=true.

Query parameters

Example request

GET https://app.regrid.com/api/v2/batch/jobs?token=<token>

Example response

{
  "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,
      "processed_count": 102,
      "failed_count": 0,
      "time_remaining": 0
    }
  ]
}

Download Batch Job Results

GET /batch/{job_uuid}/download

Downloads the completed results for a batch job. Only available when the job status is ready. Results are returned as newline-delimited GeoJSON (JSONL), where each line is a single GeoJSON Feature representing a matched parcel. This format is optimized for streaming large result sets.

Path parameter

Example request

GET https://app.regrid.com/api/v2/batch/9fa5920e-29ab-49a7-98a9-e781da6385c8/download?token=<token>

Response format

Results are returned as JSONL — one GeoJSON Feature per line. Each feature contains the matched parcel's properties (including all standard schema fields and custom_id if provided) and geometry (if return_geometry was not set to false).

{"type":"Feature","geometry":{...},"properties":{"headline":"440 Burroughs St","path":"/us/mi/wayne/detroit/364491","fields":{...},"custom_id":"point_001"}}
{"type":"Feature","geometry":{...},"properties":{"headline":"123 Main St","path":"/us/ca/los-angeles/downtown/123456","fields":{...},"custom_id":"point_002"}}

Error responses

Delete a Batch Job

DELETE /batch/{job_uuid}

Deletes a batch job and all associated data, including the input points, parameters, any generated download files, and the callback URL if one was set. Jobs are automatically deleted 30 days after creation, but you can delete them earlier to clean up or remove sensitive data.

Path parameter

Example request

DELETE https://app.regrid.com/api/v2/batch/9fa5920e-29ab-49a7-98a9-e781da6385c8?token=<token>

Example response

{
  "message": "Job removed"
}

Limits