Skip to content
GeoBridge logo GeoBridge logo GeoBridge Docs

Get started

Geobridge pairs Pelias-compatible search endpoints with an asynchronous bulk pipeline. This guide walks through the end-to-end flow using cURL so you can adapt it to any stack.

1. Create an API key

Section titled “1. Create an API key”

Visit the Geobridge dashboard and copy a production API key. Every request below authenticates with the X-API-Key header.

Tip: Store the key in an environment variable so you never paste it into code or shell history.

2. Submit a bulk job

Section titled “2. Submit a bulk job”

Send the payload location and optional webhook callback to /v1/bulk/jobs. The example below submits a small inline request. Replace YOUR_API_KEY with the secret you generated above.

Terminal window
curl -s -X POST 'https://api-na.geobridge.io/v1/bulk/jobs' \
  -H 'Content-Type: application/json' \
  -H "X-API-Key: ${GEOBRIDGE_API_KEY}" \
  -H 'X-Idempotency-Key: quickstart-001' \
  -d '{
    "input": {
      "transport": "inline",
      "records": [
        { "id": "1", "text": "1600 Amphitheatre Parkway Mountain View" },
        { "id": "2", "text": "1 Apple Park Way Cupertino" }
      ]
    },
    "callback": {
      "url": "https://example.org/bulk/callback",
      "secret": "${GEOBRIDGE_WEBHOOK_SECRET}"
    },
    "options": {
      "output_format": "ndjson"
    }
  }'

The response returns a job_id. Keep it handy for polling.

3. Poll job status

Section titled “3. Poll job status”

Use the job ID to check progress. A 409 Conflict indicates the job is still running, while 200 OK returns metadata including completion timestamps.

Terminal window
curl -s 'https://api-na.geobridge.io/v1/bulk/jobs/{job_id}' \
  -H "X-API-Key: ${GEOBRIDGE_API_KEY}" | jq

4. Stream NDJSON results

Section titled “4. Stream NDJSON results”

Once status transitions to succeeded, request the results with format=ndjson and set Accept: application/x-ndjson to switch on streaming. Each line emitted is a discrete match payload that you can pipe into downstream workers immediately.

Terminal window
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

Need pagination instead? Supply the cursor query parameter returned in the payload to fetch the next slice.

5. Clean up (optional)

Section titled “5. Clean up (optional)”

Delete test runs once you are done so they do not count toward storage quotas.

Terminal window
curl -s -X DELETE 'https://api-na.geobridge.io/v1/bulk/jobs/{job_id}' \
  -H "X-API-Key: ${GEOBRIDGE_API_KEY}"

Next up

Section titled “Next up”