Bulk Jobs

Run high-volume imports through Geobridge and stream results as soon as matches are ready. The bulk API pairs asynchronous processing with NDJSON delivery so you can fan out work without waiting for archives to download.

OpenAPI links

The complete schema lives in openapi.yaml. Download it here. Jump directly to POST /bulk/jobs, GET /bulk/jobs/{job_id}, and GET /bulk/jobs/{job_id}/results for human-readable details.

Endpoints at a glance

Method	Path	Description	Try it
POST	/v1/bulk/jobs	Create a job from an HTTPS, S3, or inline payload. Optionally configure a webhook callback.
GET	/v1/bulk/jobs/{job_id}	Poll job metadata including lifecycle timestamps and failure details.
DELETE	/v1/bulk/jobs/{job_id}	Cancel or purge a completed job.
GET	/v1/bulk/jobs/{job_id}/results	Retrieve results inline, via a presigned URL, or as a streaming NDJSON feed.

Streaming NDJSON results

Set format=ndjson and request Accept: application/x-ndjson to receive a live feed of records. Each line is a standalone JSON document that maps the original id to the matched features.

cURL

curl -s -N 'https://api-na.geobridge.io/v1/bulk/jobs/{job_id}/results?format=ndjson' \
  -H 'Accept: application/x-ndjson' \
  -H "X-API-Key: ${GEOBRIDGE_API_KEY}" \
  | tee results.ndjson

Each newline is a valid JSON document. Pipe it into jq, queue workers, or downstream storage without waiting for the full job to complete.

Node.js

const apiKey = process.env.GEOBRIDGE_API_KEY;
const jobId = process.env.GEOBRIDGE_JOB_ID;
const url = new URL(`/v1/bulk/jobs/${jobId}/results`, 'https://api-na.geobridge.io');
url.searchParams.set('format', 'ndjson');

const response = await fetch(url, {
  headers: {
    'Accept': 'application/x-ndjson',
    'X-API-Key': apiKey,
  },
  signal: AbortSignal.timeout(30000),
});

if (!response.ok || !response.body) {
  throw new Error(`Bulk results failed: ${response.status} ${response.statusText}`);
}

const decoder = new TextDecoder();
let buffer = '';

for await (const chunk of response.body) {
  buffer += decoder.decode(chunk, { stream: true });
  const lastBreak = buffer.lastIndexOf('\n');
  if (lastBreak === -1) continue;
  const ready = buffer.slice(0, lastBreak).split('\n');
  buffer = buffer.slice(lastBreak + 1);

  for (const line of ready) {
    if (!line) continue;
    const doc = JSON.parse(line);
    console.log(doc.id, doc.matches?.[0]?.properties?.name);
  }
}

Python

import json
import os
import requests

api_key = os.environ["GEOBRIDGE_API_KEY"]
job_id = os.environ["GEOBRIDGE_JOB_ID"]

resp = requests.get(
    f"https://api-na.geobridge.io/v1/bulk/jobs/{job_id}/results",
    headers={
        "Accept": "application/x-ndjson",
        "X-API-Key": api_key,
    },
    params={"format": "ndjson"},
    stream=True,
    timeout=30,
)
resp.raise_for_status()

for line in resp.iter_lines():
    if not line:
        continue
    doc = json.loads(line)
    print(doc["id"], len(doc.get("matches", [])))

Cursor-based pagination

Large jobs may paginate results even in NDJSON mode. When the response body contains cursor, call the same endpoint with ?cursor=<value> to continue streaming the next slice.

Response schema

GET /bulk/jobs/{job_id}/results returns a BulkJobResults document:

• job echoes the metadata from GET /bulk/jobs/{job_id} so you can reconcile status without an extra request.
• format reflects the payload you requested (geojson, ndjson, or csv).
• results contains one of:
  • a GeoJSON feature collection (inline when format=geojson and the payload is small),
  • a presigned URL for large archives, or
  • a stream of newline-delimited strings for NDJSON.

Refer to #/components/schemas/BulkJobResults for exact field definitions.

Webhooks and retries

Pair streaming with a webhook to learn when Geobridge finishes processing. Configure the webhook when you create the job:

callback object

{
  "url": "https://example.org/bulk/callback",
  "secret": "${GEOBRIDGE_WEBHOOK_SECRET}",
  "retry_policy": {
    "max_attempts": 5,
    "strategy": "exponential"
  }
}

See the Bulk job completion callback for the signing algorithm and replay mitigation guidance.