Geocoding
GeocodingGeocodingConverting an address into map coordinates so a job or resource can be placed on the map and used for routing. turns an address into a coordinate so the map knows where to drop a pin. It underpins the map component and everything that depends on it (route planning, distance calculations, dispatch decisions), so getting it right matters.
Two entities appear on the map and therefore need coordinates:
How Dime.Scheduler reads an address
Each job and resource exposes three address field sets. Dime.Scheduler uses them in descending order of accuracy and stops at the first one that yields a usable result:
- Latitude and longitude. When a coordinate already exists, those values are used directly. No text parsing is needed and the record is considered geocoded.
- Separate address fields. When the coordinate is missing, Dime.Scheduler combines the dedicated street, street number, zip code, city, state, and country fields and asks the geocoding provider to resolve them.
- Full address. When the structured fields are incomplete, Dime.Scheduler falls back to the free-text address field.
For resources, this is the "Home Address" set on the resources page. For jobs, it is the "Site Address" range on the jobs page.
Always populate the dedicated columns when you can. Free-text addresses are notoriously hard to interpret because there is no universal format: in some countries the street number comes before the street name ("1 Rue d'Avignon"), in many others it comes after ("Rue d'Avignon 1"). Structured fields remove that ambiguity.
Getting geocoding to work end-to-end
Follow these steps the first time you set up an environment, after a bulk data import, or whenever the map shows fewer pins than you expect.
1. Make sure addresses arrive in the right columns
In the resources view and the jobs view, confirm that addresses populate the structured fields (street, zip, city, country) rather than landing entirely in the free-text address field. The originating back-office system is the master here, so the cleanest fix is usually upstream of Dime.Scheduler.
2. Put an ISO country code in the country field
The country field on the job and resource address is sent to the provider as-is, with no mapping in between. Type an ISO 3166 code ("US", "BE", "DE") rather than a localized name ("Belgique", "Belgien", "Belgium"). If the value comes from a back-office system, normalize it there before it reaches Dime.Scheduler.
3. Trigger geocoding
Three triggers exist, in increasing scope:
- Per-row geocode button . On the jobs and resources grids, every row has a small map-pin button. Use it after fixing a single address: it geocodes that one record on demand.
- Geocode All in the toolbar. This geocodes every job (or resource) that does not yet have coordinates. It is the same routine the nightly job runs, just on demand.
- Nightly background job. Dime.Scheduler runs a scheduled job that picks up every job and resource without coordinates and geocodes them in the background. This is what processes newly imported records overnight without any manual action.
4. Refresh and inspect the map
After the geocoder finishes, refresh Dime.Scheduler. Records that resolved successfully now appear on the map component. Records that did not resolve stay coordinate-less and are skipped by the map.
The blacklist
To avoid retrying the same unresolvable address on every run, Dime.Scheduler maintains a blacklist of address signatures it has already tried and failed to resolve.
An entry is added to the blacklist when one of the following happens:
- The address looks too incomplete or implausible to even attempt (for example a free-text field with only a few characters, or a structured address missing too many parts). These are rejected before the provider is called.
- The provider was called but returned no coordinate. The address is recorded so the next nightly run does not retry it.
A blacklist entry stores the address signature together with the country code, so the same street name in two different countries is treated as two distinct entries.
What this means in practice
- A record on the blacklist is silently skipped by the geocoding routines, including the per-row button, the Geocode All button, and the nightly job. The record stays without coordinates and stays off the map.
- The blacklist exists per address signature, not per record. Many jobs that share the same incomplete site address will all be skipped by a single entry.
- Fixing the address in the back-office system or directly on the record does not automatically remove the old signature from the blacklist. If the address you just corrected is still not getting pinned on the map, the previous (broken) version of that address may still be blacklisted under a slightly different signature, or the corrected address may resolve to a new entry. In both cases the per-row geocode button is the fastest way to verify what the geocoder actually does with the new input.
Tips for accurate results
Geocoding is only as good as the input. The rules below cover the failure modes we see most often. Most are easier to enforce in the back-office system than to clean up after the fact.
Prefer structured fields over free text
Free-text parsing has no universal rules: in some countries the number comes before the street ("1 Rue d'Avignon"), in many others it comes after ("Rue d'Avignon 1"). The provider has to guess. Structured fields remove the guess.
Keep the address fields strictly address
The street and street number fields should contain a street and a street number, nothing else. Extras that look harmless to a human are noise to the geocoder:
- No floor, suite, building, or apartment information. "10 Main Street, Building B, 3rd floor, Suite 301" parses worse than plain "10 Main Street". If the back-office system needs the suite, store it in a separate notes field that Dime.Scheduler does not send to the provider.
- No company or contact names. "Acme Corp, 10 Main Street" belongs as two fields: company name on the customer record, "10 Main Street" in the address.
- No directional hints. "10 Main Street (next to the petrol station)" cannot be resolved to a coordinate and usually ends up blacklisted.
- No placeholders. "TBD", "Unknown", "Same as billing", "-", and empty strings will never resolve.
Use a real street number, not a range
"10-12 Main Street" forces the provider to pick a side. Use the primary entrance number.
Avoid PO boxes for site addresses
A PO box has no physical coordinate. The provider will either fail or return the post office, which is not where the work happens.
Make the postcode match the city
A London postcode with "Manchester" in the city field forces the provider to guess. Most back-office systems can validate postcode/city pairs at entry time.
Be specific enough to be unambiguous
"Papa John's Pizza, Rome" is ambiguous: the provider is likely to return the Italian capital rather than the small city in Floyd County, Georgia. Include the country, and the postcode when you have it.
If you must use free text, pick one format and stick to it
Choose one ordering (for example "street number, street, postcode, city, country") and apply it consistently across the dataset. Mixing orderings means you cannot reason about hit rates.
Fix the master data upstream
Repeated failures usually trace back to bad master data in the back-office system. Cleaning the address at the source benefits every system that consumes it, and prevents the same record from being re-imported broken on the next sync.
Troubleshooting
| Symptom | Likely cause | What to try |
|---|---|---|
| A record does not appear on the map after geocoding | The address could not be resolved and the record has no coordinates | Verify the structured fields and the country code, then click the per-row geocode button to retry |
| Many newly imported records are missing from the map | Nightly job has not run yet | Wait for the next nightly run, or click Geocode All in the toolbar |
| A record stays uncoordinated even after you corrected the address | The previous version of the address is on the blacklist, or the corrected address is unresolvable too | Use the per-row geocode button to see what happens with the new input. If it still fails, contact support to investigate the blacklist |
| The pin lands in the wrong country or city | Ambiguous free-text address, or a non-ISO country value | Move the data into the structured fields and ensure the country uses an ISO 3166 code |