Skip to Content
GeocodingOverview

Geocoding

For: everyone. If you are deciding whether to use the product, read this whole page.

ModularIoT geocoding turns the place a trip declares into a point on the map and a GPS geofence. The place can come as a geofence code, a Plus Code, coordinates or an address. With the geofence, the platform detects when the truck arrives at the origin or the destination.

What it solves

A trip says where it leaves from and where it goes. If that place has no geofence, the platform cannot see the arrival or the departure. Without geocoding, someone has to draw each geofence by hand.

With geocoding:

BeforeNow
Each new place waits for someone to draw its geofenceThe place is located when the trip arrives
A misspelled address leaves the trip untracked and nobody noticesThe place goes to To review with the reason
Each call to a map service costs money, and nobody knows how many are madeEach automatic resolution is recorded with its source and its cost

How a place is located

The platform tries sources in order and keeps the first one that gives a point. The first ones are free. Only the last one costs money.

OrderSourceExample inputCost
1Existing geofence, by code or nameCD-01Free
2Plus Code57V4VXHC+H4, or VXHC+H4 with the districtFree
3Coordinates-33.4569, -70.5976Free
4Internal addresses (Chile only today)Av. Providencia 1208Free
5Cache of earlier resultsAn address already looked upFree
6Provider (Mapbox or Google)A new addressOne call, within the quota

Then the platform checks that the point falls in the declared district, with 500 m of tolerance. If it does, it uses the geofence that already contains the point or creates a circular geofence. If it does not, or if no source gave a point, the place goes to To review. A person places it on a map.

Step by step in How the source is chosen.

What it costs

Only a call to the provider counts. Geofences, Plus Codes, coordinates, internal addresses and the cache use no quota.

ItemWho sets itWhere
Cost per call that the provider charges the platformThe contract with the providerSettings › Connections, in the Platform scope
Monthly plan price, included calls and price per call over the quotaThe platform ownerSettings › Platform › Geocoding › Plan
Each organization’s quota and what happens when it runs outThe platform ownerSettings › Platform › Geocoding › Organizations
Whether the quotas apply (Apply the quotas)The platform ownerSettings › Platform › Geocoding › Plan
Which organizations can call the providerThe platform ownerEach organization’s Settings › Connections: the Geocoding · platform provider connection

A place is located once. Later trips to the same place use its geofence and make no new call. So the cost per trip goes down over time:

SituationProvider calls per trip
Origin and destination already located0
New destination with an address in the internal addresses or in the cache0
New destination with an address nobody looked up before1
New origin and destination, both with new addresses2

The owner of each organization sees its month’s usage in Settings › Trips › Monthly usage. Details in Usage, cost and monitoring.

What depends on the country

The source order, the cache, the quota and the API are the same in every country. Each country also needs its administrative boundaries (communes or districts) and, where they exist, its address sources.

CountryAdministrative boundariesInternal addressesProvider
ChileCommunesYes (OpenAddresses)Mapbox
PeruDistrictsNoMapbox. Not certified: many addresses go to review
OthersNoNoEvery place goes to review

Pitfall: a place with no country, or from a country without administrative boundaries, always goes to review, even with coordinates or a geofence code. The district check requires them.

How to add a country in Certify a new country.

Risks

RiskEffectWhere it shows
The provider returns a wrong point inside the right districtThe geofence is in the wrong place and the arrival is not detectedThe trip does not change stage on arrival. Fix it in Locations
The provider does not find the exact address (only the street or the city)The place goes to reviewSettings › Trips › To review
The organization uses up its quotaDepending on its plan: places go to review, or each call is charged as overageMonthly usage, and an alert at the plan’s percentage
Two of the customer’s geofences contain the pointThe one with the lowest id is usedNo warning

Choose your path

You areYou wantStart at
Product owner or customerKnow what it does, what it costs and its risksThis page and Usage, cost and monitoring
ImplementerSet up the provider and the quota, prepare the spreadsheet and review locationsSet up the provider
DeveloperLocate places through the APIYour first location

Where a place comes in

InputWho uses it
POST /api/v1/orgs/{org}/trips/locations/resolveA system that registers places through the API
The originSite and destinationSite sites of the trip feedAn integration that sends trips, for example from a spreadsheet
Manual reviewA person who places the point on the map

How this guide is organized

SectionContent
LearnShort pages, in order, with input and output examples
How-to guidesOne task: set up the provider, assign a quota, review locations
ConceptsWhat is generic and what depends on each setup; the provider; the cost
ReferenceEvery endpoint, field, review reason, table and metric
Last updated on