On this page

Copy page

Documentation

Batches API Quickstart

Use this guide to submit an address CSV, review the quote, start a Batches v1 job, and retrieve its results.

Batches v1 processes a CSV through the Addresses v2 geocoder, reverse geocoder, or MailPoint. Submission validates the configuration and starts quoting. Processing starts after you accept the quote or enable automatic start.

Before you begin

You need:

• A Geoscape Hub application with Batches API access and access to the address products you will use
• The application's Consumer Key and sufficient credits for the quoted job
• A UTF-8 CSV at an HTTP, HTTPS, or FTP URL the service can read
• A terminal with curl and jq installed

MailPoint and premium additional properties require paid-plan access. Follow Authentication for application setup.

1. Set your Consumer Key

Code
export GEOSCAPE_API_KEY="YOUR_CONSUMER_KEY"

The header name is Authorization. Its value is the Consumer Key directly, without a Bearer prefix. The Consumer Secret is not used. The base URL is https://api.psma.com.au/v1/batches.

2. Prepare your input

Save the following as a CSV and host it at a URL the service can access:

Code
customerAddressId,address
1,113 Canberra Ave Griffith ACT 2603
2,1 Martin Place Sydney NSW 2000

The address column will be mapped to the geocoder's address parameter. The customer ID is retained in the output unless you exclude it. See Files and Mappings for structured addresses, coordinates, credentials, and JSONPath examples.

3. Submit the job for quoting

Create batch-request.json, replacing the example input URL with your hosted CSV. Omit output.file to receive a download link instead of writing results to your server:

Code
{
  "type": "addressGeocoder",
  "parameters": {"matchType": "Address"},
  "input": {
    "file": "https://example.com/input.csv",
    "format": [{"name": "address", "apiParameter": "address"}]
  },
  "output": {
    "format": [
      {"name": "Matched Address", "source": "$.features[0].properties.formattedAddress"},
      {"name": "Address ID", "source": "$.features[0].properties.addressId"},
      {"name": "Match Quality", "source": "$.features[0].matchQuality"}
    ]
  }
}

Submit the JSON and save the returned job ID:

Code
BATCH_RESULT=$(curl --fail-with-body \
  "https://api.psma.com.au/v1/batches/batch" \
  -H "Authorization: $GEOSCAPE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  --data @batch-request.json)

printf '%s\n' "$BATCH_RESULT" | jq .
BATCH_ID=$(printf '%s\n' "$BATCH_RESULT" | jq -r '.batchInfo.batchId // empty')

An accepted submission returns 200 with status: "Quoting". The ID is in batchInfo.batchId, not at the top level. The service checks file access, CSV headers, required input mappings, and output expressions before accepting the job.

4. Review the quote

If BATCH_ID is present, retrieve the job until its status is Quoted:

Code
curl --fail-with-body \
  "https://api.psma.com.au/v1/batches/batch/$BATCH_ID" \
  -H "Authorization: $GEOSCAPE_API_KEY" \
  -H "Accept: application/json"

Check:

• status, including Failed if quoting could not complete
• batchInfo.totalRows, the number of rows counted for processing
• batchInfo.estimatedCreditCost, the quoted cost in credits
• batchInfo.estimatedRunTime, an estimated duration

Use Managing Jobs to understand status transitions and how to change a quoted job.

5. Start the job

Once you have reviewed the quote and have sufficient credits, send an empty POST:

Code
curl --fail-with-body --request POST \
  "https://api.psma.com.au/v1/batches/batch/$BATCH_ID/start" \
  -H "Authorization: $GEOSCAPE_API_KEY" \
  -H "Accept: application/json"

The job enters Queued, then Running. Retrieve the job with GET to check batchInfo.progress. This field is descriptive text, not a numeric percentage.

6. Download the results

Retrieve the job again when processing completes:

Code
BATCH_STATUS=$(curl --fail-with-body \
  "https://api.psma.com.au/v1/batches/batch/$BATCH_ID" \
  -H "Authorization: $GEOSCAPE_API_KEY" \
  -H "Accept: application/json")

printf '%s\n' "$BATCH_STATUS" | jq .

if [ "$(printf '%s\n' "$BATCH_STATUS" | jq -r '.status')" = "Completed" ]; then
  DOWNLOAD_URL=$(printf '%s\n' "$BATCH_STATUS" | jq -r '.batchInfo.downloadPath // empty')
  if [ -n "$DOWNLOAD_URL" ]; then
    curl --fail-with-body "$DOWNLOAD_URL" --output batch-results.csv
  fi
fi

Use the returned download URL directly. It does not need your Consumer Key. Check messages if a completed job has no download link, as premium-data access can restrict downloads.

If the request fails

Status	What to check
400	JSON fields, file access, CSV mappings, JSONPath syntax, or whether the job's status permits the action
401	The application's Consumer Key and API access
403	Job ownership, product access, or sufficient credits to start
404	The job ID and whether the job is available
429 or 500	Follow Error Handling for rate-limit and transient-failure handling

Service errors contain messages. Gateway authentication errors can contain fault. A job can also fail asynchronously after an HTTP request succeeds, so always inspect status.

The endpoint reference provides language-specific request examples. Choose the language in the request example panel. Do not repeatedly resubmit POST requests to poll a job. Use GET with a suitable polling interval and observe Rate Limiting.

Next steps

• Configure files and mappings
• Manage batch jobs
• Assess address matches