Skip to Content
GeocodingLearnFrom point to geofence

From point to geofence

For: developers and implementers.

You will learn:

  • how the platform checks that the point falls in the declared district;
  • when the place uses an existing geofence and when one is created;
  • what radius the geofence has for each place type;
  • what each resolution records.

A source gave a point. Before trips use it, two things happen: the district check and the choice of geofence.

The declared district

Each site declares its country and its district (a commune in Chile, a district in Peru). The platform uses that data to check the point. Without it, the place needs review even if the point is correct.

DataFormatExample
countryISO 3166-1 alpha-2, case-insensitiveCL, pe
districtCodeChile: commune code (CUT, 5 digits). Peru: ubigeo (6 digits)13101, 150122
districtThe name, ignoring case, accents and repeated spacesÑuñoa, nunoa

If you send both, districtCode wins. A code that lost its leading zeros is completed: 2101 is 02101 (Antofagasta). A name that repeats in the country does not work; send the code.

SituationReview note
No countrycountry is required to check the district
Country without administrative boundaries (any except CL and PE)country AR has no district boundaries
No districtdistrict is required
Code that does not existdistrict code 99999 not found in CL
Name that repeatsdistrict Santa Rosa is ambiguous in PE; send its code
District without a polygon in the boundary datadistrict 150137 has no boundary to check against

The 500-meter rule

The point must fall inside the district or 500 m or less from its border. The district polygons are simplified, and a real point next to the border can fall just outside.

If the point falls farther away, the place needs review. The note says where it fell:

the point is in Santiago (13101), not in Providencia (13123)

If the point falls outside the country: the point is outside CL, not in Santiago (13101).

The point is stored anyway in latitude, longitude and plusCode. The person who reviews the place sees it on the map.

The geofence that already contains the point

If the point passes the check, the platform searches the organization’s GPS geofences for one that contains the point. If it finds one, it links the place to it and does not create another.

RuleDetail
Only geofences of the same organizationGeofences of other organizations are never used
Several geofences contain the pointThe one with the lowest identifier is used
Not consideredGeofences created when a place is placed by hand during review
Does not applyTo a point placed by hand: that place gets its own geofence

If the search fails (for example, the GPS database does not respond), the place needs review with the note could not check geofences for the point.

Pitfall: the search for the geofence that contains the point arrives after version 0.6.0 of the platform. In version 0.6.0, each place resolved by Plus Code, coordinates or address gets a new geofence, even if another one already covers the point.

The circular geofence

If no geofence contains the point, the platform creates a circle around the point. The radius depends on the place type:

Type (type)Radius
port1000 m
plant500 m
distribution_center300 m
zone200 m
customer150 m

A place with no type, or one the feed created with only a code, is zone: 200 m.

The new geofence is stored in the organization’s GPS database:

AttributeValue
CodeThe place’s externalCode. Without a code, its id
NameThe place’s name
ShapeA polygon with 32 vertices
Propertiescreated_by: miot-trips, location_id, location_type, resolution_source, plus_code

Because the geofence code is the externalCode, a second resolution of the same place finds it by code (source 1) and does not create another. A customer geofence that already contained the point keeps its own code: on a second resolution source 1 does not find it, and the containment search chooses it again.

If the organization has no GPS database configured, the geofence cannot be created and the place needs review with the note the GPS database is not configured.

What is recorded

WhereWhat
The locationThe point, the Plus Code, the source, the status, the note and the geofence
Trips audit logA location.resolved or location.needs_review entry, with the source and the geofence
Geocoding usage recordOne row per POST /resolve or feed site: source, result, provider, whether it was a cache hit and the cost. Placing by hand and rejecting write no row
Open trips at that placeThey are recalculated, so they use the new geofence

The details of each record are in Data and metrics.

Summary

  • The point must fall in the declared district, with 500 m of tolerance. If not, the place needs review.
  • If a geofence of the organization contains the point, that one is used.
  • If not, a circle is created with the radius of the place type.
  • The code of a created geofence is the place’s externalCode.

Next: Locations that need review.

Last updated on