​

HERE Batch Geocoding

Batch geocoding is not a bulk endpoint. It is a job API, with a lifecycle you must manage. Teams reach for it expecting POST /geocode with an array. They get a job ID, a status URL, and a set of behaviours that look like errors and are not.

​

What problem this guide solves

You have 4 million customer addresses to normalize. Nothing is waiting. A user is not watching a spinner. Paying real-time geocoding rates for this is the second-largest avoidable cost on the platform, after not caching at all. Batch is cheaper per record, and the only thing you give up is latency you were not using.

​

When to use Batch API

• Bulk address normalization on import
• Backfilling coordinates for an existing customer or location table
• Nightly enrichment pipelines
• Processing partner data files
• Historical telematics enrichment via batch reverse geocoding
• Any workload where the result is written to a database rather than rendered to a screen

The tell: if nothing is waiting for the answer, it should have been batched.

​

When NOT to use it

• A user is waiting. Checkout address entry, dispatcher lookup. Use real-time geocoding.
• The address is already in your cache. Batch is cheap. Cached is free.
• Fewer than a few hundred records. Job overhead exceeds the saving.
• You need results within seconds. Jobs are asynchronous by design and by nature.
• You want a bulk endpoint. This is not that. It is a job lifecycle.

​

The job lifecycle

Six steps. Skipping any of them produces the failure modes below.

1. Create — POST the job → 201 with a job ID
2. Start — begin processing
3. Poll status — until the job reaches a terminal state
4. Retrieve results — as a downloadable stream
5. Retrieve errors — separately, if any
6. Delete — clean up

HERE documents job status, job lifecycle, and limits and performance as three separate concerns. Read all three before you write the pipeline. The limits page in particular will determine your architecture.

​

Status codes that are not errors

This section exists because these three produce more support tickets than everything else combined.

​

Code examples

The pipeline logic below is what matters, and it is platform-independent.

​

Production architecture

Persist the job ID before you poll. If your worker restarts mid-poll, you resume. You do not resubmit. Resubmitting a 4-million-record job bills 4 million records again. Poll with backoff. A job that takes forty minutes does not need to be checked every two seconds. Respect the concurrency limit. Queue jobs. A 429 on start means you already have as many running as your entitlement allows. Firing retries in a loop achieves nothing. Use gzip. Compression is supported and worth it on large inputs. Upload time and bandwidth both drop materially. Handle partial success. Some records fail. The errors endpoint tells you which. A pipeline that assumes all-or-nothing will either discard 3.9 million good results or persist 100,000 bad ones. Delete completed jobs. They accumulate. Cleanup is step six for a reason. Webhooks exist in beta. HERE supports completion notifications with substitutable placeholders like ${JOB_ID} and ${JOB_STATUS}. Attractive — but beta. If your nightly pipeline’s correctness depends on a webhook arriving, build the polling fallback anyway. Normalize before you submit. Trim, case-fold, and expand abbreviations first. It increases your cache hit rate on the next run and reduces records that fail to match. Write results into your cache, not just your table. The point of batch geocoding is that you never geocode that address again. See Geocoding.

​

Cost and usage considerations

Batch is cheaper per record than real-time. That is the entire commercial case, and it is sufficient. Where teams overspend:

• Never batching at all. Real-time rates for overnight work.
• Re-batching unchanged records. Filter on geocoded_at IS NULL before you build the input file.
• Resubmitting jobs after a worker crash. Persist the job ID.
• No caching downstream. You paid once. Do not pay again next month.
• Batching what should have been cached. If your input file contains the same address 400 times, deduplicate it before submission.

Geocoding-heavy workloads see the largest savings when moving from Google — typically 80%+ at production volume. That figure assumes the pipeline is already sane. Migrating an unbatched, undeduplicated pipeline moves waste to a cheaper meter. See HERE Pricing Explained.

​

Common mistakes

Treating Batch API as a bulk endpoint. It is a job lifecycle. Poll it. Retrying 204 from the errors endpoint. Zero errors. Retrying 404 on results aggressively. The job has not finished. Hammering after a 429 on start. Concurrency limit. Queue. Losing the job ID on restart. Full rebill. Assuming all-or-nothing. Read the errors endpoint. Never deleting jobs. Depending on a beta webhook without a polling fallback. Not deduplicating the input file. Not writing results back into a persistent cache. You will do this again next quarter, and pay again.

​

Best practices

• Deduplicate and normalize the input before submission
• Persist the job ID before the first poll
• Poll with exponential backoff
• Queue against the concurrency limit rather than retrying 429
• Compress large inputs with gzip
• Read the errors endpoint; handle partial success explicitly
• Delete jobs after retrieval
• Write results into a durable cache keyed on normalized address
• Build the polling path even if you use webhooks
• Filter on already-geocoded records before every subsequent run

​

API reference

• Batch API v7 quick start
• Job lifecycle
• Job status
• Limits and performance
• Batch reverse geocoding

​

Related guides

Also: Authentication · Batch Geocoding

---

Need production HERE API keys or implementation support? Placematic is an official HERE Technologies reseller and implementation partner helping companies choose the right HERE APIs, estimate usage, migrate from Google Maps and build production-ready geospatial solutions. Talk to us.