Skip to Content
GeocodingLearnHow the source is chosen

How the source is chosen

For: developers and implementers.

You will learn:

  • in what order the six sources are tried and which one responds;
  • what each source needs to give a point;
  • why an address was resolved for free or cost one call;
  • how to read resolutionSource.

The idea

A site can carry several pieces of data at once: a code, a Plus Code, coordinates and an address. The platform does not combine them. It tries the sources in a fixed order and uses the first one that gives a point. Then it checks that point against the declared district.

OrderSourceNeedsresolutionSource
1Customer geofenceA geofence with the place’s code or namegeofence
2Plus CodeplusCode. A short one also needs the districtplus_code
3Coordinateslatitude and longitudecoordinates
4Internal addressesaddress, a district with a boundary, a country with an internal sourceinternal
5Cacheaddress and a district with a boundaryprovider
6ProviderThe same, and available quotaprovider

Sources 1 to 3 give a point without looking up the address. If one of them responds, the address is not used. So a site with coordinates and an address is located by the coordinates, even if the address is a different place.

The cache and the provider share the value provider: the cache stores provider results. The usage record tells one case from the other (see Usage, cost and monitoring).

Before trying the sources, the platform looks up the declared district. If the country is missing or has no administrative boundaries, the place needs review even if a source gives a point. The full rule is in From point to geofence.

1. Customer geofence

The platform searches your organization’s GPS geofences for one whose code is the place’s code (externalCode) or whose name is the place’s name (case-insensitive). The code wins over the name. If two geofences have the same name and neither has the code, the source does not respond.

The point is the center of the geofence.

{ "externalCode": "ANF", "country": "CL", "district": "Antofagasta" }
{ "externalCode": "ANF", "geofenceId": 1204, "plusCode": "578F6MGR+4J", "resolutionSource": "geofence", "resolutionStatus": "resolved" }

Geofences of other organizations are never used.

2. Plus Code

A Plus Code  (Open Location Code) describes a small area. The point is the center of that area.

FormExampleNeeds
Full57V4VXHC+H4Nothing else
ShortVXHC+H4The district, by districtCode or by district

A short code is completed with the center of the declared district. The platform reads only the first word of plusCode. In VXHC+H4 Miraflores, the text Miraflores is not used: the district comes from districtCode or district.

{ "externalCode": "DOC-GEO-PC-SHORT", "country": "PE", "districtCode": "150122", "plusCode": "VXHC+H4" }
{ "plusCode": "57V4VXHC+H4", "district": "MIRAFLORES", "latitude": -12.1210625, "longitude": -77.0296875, "resolutionSource": "plus_code", "resolutionStatus": "resolved" }

Pitfall: Peru has two districts named Miraflores (Lima and Arequipa). With "district": "Miraflores" and no districtCode, the district cannot be chosen and the place needs review with the note district Miraflores is ambiguous in PE; send its code. Send the code: "districtCode": "150122".

An invalid Plus Code does not stop the search: the platform moves on to the coordinates and then to the address. If no later source responds, the note is plus code … is not valid.

3. Coordinates

latitude and longitude go together, in decimal degrees (WGS 84). These cases give no point; if the site has an address, the search continues with it:

CaseNote
Only one of the twolatitude and longitude go together
Out of range, or exactly 0, 0coordinates out of range
{ "externalCode": "DOC-GEO-COORD", "country": "CL", "districtCode": "13101", "latitude": -33.4378, "longitude": -70.6505 }
{ "plusCode": "47RFH86X+VR", "district": "Santiago", "resolutionSource": "coordinates", "resolutionStatus": "resolved" }

4. Internal addresses

Internal addresses are a table of addresses with their point, loaded in the GPS database. Today there is one for Chile, with data from OpenAddresses. Looking it up costs nothing.

The platform splits the address into street and number:

RuleExample
Uses the text before the first commaCamino Lo Boza 120, Pudahuel → Camino Lo Boza 120
Removes everything from Of, Ofic, Oficina, Depto, Dpto, Dep, Local, Bodega, Piso or Lote to the endAv. Apoquindo 3000 Of 501 → Av. Apoquindo 3000
Removes #, N°, Nro. before the numberCalle Uno N° 45 → Calle Uno 45
The last number of 1 to 5 digits is the house numberRuta 5 Sur 1234 → street Ruta 5 Sur, number 1234

It tries three forms of the street: as written, without accents or punctuation, and without the street type (Av, Avda, Avenida, Calle, Pasaje, Pje, Psje). One of them, and the number, must match the table in the declared district.

Address sent (district San Bernardo)Result
Presidente Jorge Alessandri Rodríguez 10700internal: the name matches the table
Av. Jorge Alessandri Rodriguez 10700No match: the official name includes Presidente. Moves on to the cache and the provider
{ "externalCode": "DOC-GEO-INTERNA", "type": "plant", "country": "CL", "district": "San Bernardo", "address": "Presidente Jorge Alessandri Rodríguez 10700" }
{ "districtCode": "13401", "plusCode": "47RFC8X2+GC", "resolutionSource": "internal", "resolutionStatus": "resolved" }

5. Cache

When the provider gives a point that falls in the declared district, the platform stores it in a cache shared by all organizations. The cache stores the normalized address, the country, the point and the provider’s name. It does not store the organization, the place’s name or the provider’s response.

The key is the district code plus the address without accents or punctuation, with the district name at the end if the address does not include it. These two addresses have the same key in Pudahuel (13124):

AddressKey
Camino Lo Boza 120, Pudahuel13124|CAMINO LO BOZA 120 PUDAHUEL
camino lo boza 12013124|CAMINO LO BOZA 120 PUDAHUEL

A cache hit uses no quota. The response says provider, because the point came from the provider in another lookup.

Provider resultWhat happens
Mapbox with permanent mode, inside the districtIt is used and stored in the cache
Mapbox with permanent mode, outside the districtIt is not stored. The place needs review
Mapbox without permanent modeIt is not used. The place needs review
GoogleIt is not used. The place needs review

In the last two cases the note is geocoding results cannot be stored with this provider configuration, and the call is charged. The terms of Google and of Mapbox without permanent mode do not allow storing the point, and the platform stores the point of each location.

Pitfall: with Google as the provider, no address is resolved by the provider. Use Mapbox with permanent mode.

6. Provider

If none of the above responded, the platform calls the platform’s provider (Mapbox or Google). First it checks two things:

CheckIf it fails
With Apply the quotas on: the organization has a subscription and quota left, or its plan says Charge overageIt does not call the provider. Note geocoding: the organization has no geocoding plan or geocoding: the organization used its N geocoding resolutions for this month
The organization has the Geocoding · ModularIoT connection in ConnectionsIt does not call the provider. Note geocoding: this organization has no geocoding connection; a platform owner adds it in Settings › Connections

With Apply the quotas off, the quota is not checked. How to set up both in Set up the provider.

The call carries the address, the district and the country:

Data sent to the providerExample
TextAv. Libertador Bernardo O'Higgins 1058, Santiago
Country (filter)cl

From the results, the platform accepts only address-level ones: with Mapbox, feature_type equal to address; with Google, street_address, premise or subpremise. A street, a neighborhood, a business or a city does not count. Among the accepted ones, it chooses the first that falls in the district. If none does, it uses the first one, and the district check sends it to review.

{ "externalCode": "DOC-GEO-PROVEEDOR", "country": "CL", "districtCode": "13101", "address": "Av. Libertador Bernardo O'Higgins 1058" }
{ "plusCode": "47RFH84X+6J", "latitude": -33.444441, "longitude": -70.650967, "resolutionSource": "provider", "resolutionStatus": "resolved" }

An address the provider does not know can come back in another district:

{ "externalCode": "DOC-GEO-SIN-NUMERO", "country": "CL", "districtCode": "13101", "address": "Calle Inexistente Doc 123" }
{ "resolutionSource": "provider", "resolutionStatus": "needs_review", "resolutionNote": "the point is in Quilicura (13125), not in Santiago (13101)" }

That call is charged anyway: the provider responded.

Summary

If the site carriesRespondsCost
The code of an existing geofencegeofenceFree
A full Plus Code, or a short one with the districtplus_codeFree
CoordinatescoordinatesFree
A Chilean address written as in the tableinternalFree
An address the provider already located in that districtprovider (cache)Free
A new addressproviderOne call

Next: From point to geofence.

Last updated on