Batch Processing

Submit places for enrichment asynchronously via batch endpoints.

Endpoints

Action	Method & Path
Create batch	POST /v1/{org_slug}/place_enrichment/batches
Get batch status	GET /v1/{org_slug}/place_enrichment/batches/{batch_id}
Get batch results	GET /v1/{org_slug}/place_enrichment/jobs?batchId={batch_id}&limit={n}&offset={n}
Reprocess batch	POST /v1/{org_slug}/place_enrichment/batches/{batch_id}/reprocess
List batches	GET /v1/{org_slug}/place_enrichment/batches?limit={n}&offset={n}

Quick Start

Submit a minimal batch via the Create batch endpoint:

Request

{
  "batch_name": "Q1 Store Locations",
  "jobs": [
    {
      "place_id": "store_001",
      "inputs": {
        "name": "Downtown Store",
        "full_address": "123 Main St, New York, NY 10001",
        "latitude": 40.7128,
        "longitude": -74.0060
      }
    }
  ],
  "attributes": ["websites", "phoneNumbers", "categories"]
}

Include full_address in jobs[].inputs when available — it improves enrichment accuracy.

The same response shape is returned by Create batch and Get batch status. The jobs object lists place IDs grouped by their job status (see Monitoring Progress).

Response

{
  "id": "d98e206f-ff1d-4b5a-b0d8-18fff0757fef",
  "batch_name": "Q1 Store Locations",
  "status": "pending",
  "jobs": {
    "pending": ["store_001"],
    "queued": [],
    "in_progress": [],
    "completed": [],
    "failed": []
  }
}

Batch Limits

Maximum places per request: 50,000

Requests exceeding this limit return 400 Bad Request. Split larger datasets into multiple batches (for example, up to 50,000 places per batch).

Batch Status Lifecycle

Batches move through a small set of statuses driven by job state. The top-level status aggregates all jobs in the batch (e.g. in_progress if any job is still running). A batch is finished when status is completed or failed.

1. Not Started: Batch created; jobs are pending and not yet queued for processing.
2. Queued: Jobs are scheduled and waiting to be picked up by workers.
3. Processing: Jobs are actively being enriched by workers.
4. Completed: All jobs finished successfully.
5. Failed: Batch failed (e.g. too many job failures).

Monitoring Progress

1. Poll for batch status

   Call GET /batches/{batch_id} on an interval (e.g. every 5–10 seconds).

2. Stop when terminal

   Stop polling when top-level status is completed or failed.

Batch status response

The response exposes job-level status via the jobs object. Each key is a job status; each value is an array of place IDs whose enrichment job is in that status. Use the array lengths to derive progress (e.g. jobs.completed.length + jobs.failed.length over total).

Field	Description
id	Batch identifier
batch_name	Display name
status	Aggregated batch status (pending, queued, in_progress, completed, failed)
jobs	Place IDs grouped by job status: pending, queued, in_progress, completed, failed
metadata	Optional: total_jobs, completed_jobs, status_counts, success_rate
created_at	Batch creation timestamp

jobs is keyed by job status, not counts. Each array contains the place_id values for jobs in that status. Total jobs = sum of lengths across all job arrays.

{
  "id": "d98e206f-ff1d-4b5a-b0d8-18fff0757fef",
  "batch_name": "Q1 2024 Store Locations",
  "status": "in_progress",
  "jobs": {
    "pending": ["store_001", "store_002"],
    "queued": ["store_003", "store_004"],
    "in_progress": ["store_005"],
    "completed": ["store_006", "store_007"],
    "failed": []
  },
  "created_at": "2024-01-15T10:00:00Z"
}

Handling Results

Fetch results

1. Request jobs for a batch

   Use the Get batch results endpoint with batchId, limit, and offset. Returns { jobs, total, limit, offset }.

2. Paginate through all results

   Increment offset by limit until offset + jobs.length >= total.

Success vs failed jobs

Each job in the jobs array has a status field. Filter by:

• status === "completed" — successful enrichments; use outputs for enriched data
• status === "failed" — failures; inspect for retry or manual review

Per-attribute run status (e.g. which enrichments ran or failed) lives under job_metadata.attribute_status. Use this for partial successes or to decide which attributes to reprocess.

Attribute status values

Value	Meaning
RUN	Enrichment ran successfully
NOT_RUN	Enrichment was not executed
ERROR	Enrichment failed
RUN_CONDITION_FAILED	Skipped (missing required inputs)

Reprocessing Failed Items

POST /batches/{batch_id}/reprocess re-queues jobs for enrichment. Key options:

Param	Default	Description
failed_only	true	Only reprocess jobs with failed status
incomplete_only	false	Only reprocess pending/queued/in_progress
refresh	false	Force fresh enrichment, ignore cached data
attributes	—	Override attributes to enrich
attribute_set	—	Use predefined set: core, all, open_closed

Set failed_only: false and incomplete_only: false to reprocess all jobs in the batch.

Listing Batches

GET /batches?limit={n}&offset={n}&query={search} returns paginated batches. Each batch includes id, batch_name, status, status_counts, created_at, and optional metadata.

Best Practices

• Descriptive batch names — Use names that identify the dataset or run so you can find them in the list.
• Chunk large datasets — Stay under 50K jobs per request; split into multiple batches or append via repeated requests with the same batch_id.
• Handle failures — Check jobs.failed after completion; use the reprocess endpoint to retry with failed_only: true.

Next Steps

• Learn about Place Enrichment for single-item enrichment
• Explore Geofencing for location-based batch queries
• Check the API Reference for complete endpoint documentation