Site Coordinates & Geofences

Coordinates sent through the Importer APIs are what turn an imported Site into live truck tracking. Get them right and arrivals, departures, and cycle times post on their own. Get them wrong and the Site imports with no fence around it, and every load needs a phone call.

Send lat and lon together

Include lat and lon on every Site in your sites array. Those two values are what Tread builds the geofence (a virtual fence around a Site) from. Send both or neither.

{
  "projects": [
    {
      "external_id": "PRJ-2025-014",
      "customer": { "external_id": "CUST-441" },
      "sites": [
        {
          "waypoint": "pickup",
          "external_id": "SITE-QUARRY-1",
          "name": "Quarry Rd Scale House",
          "site_type": "Quarry",
          "full_address": "4500 Quarry Rd, Denver, CO",
          "lat": 39.812345,
          "lon": -105.087654
        },
        {
          "waypoint": "drop_off",
          "external_id": "SITE-JOB-19",
          "name": "Main St Paving",
          "site_type": "JobSite",
          "full_address": "800 Main St, Denver, CO",
          "lat": 39.745210,
          "lon": -104.998320
        }
      ]
    }
  ]
}

Format rules:

Signed decimal degrees. Longitude is negative in North America. No N/W suffixes and no degrees-minutes-seconds.
Six decimal places, maximum. Tread stores six, which is about 4 inches. Extra digits get rounded off, so there’s nothing to gain by sending twelve.
Numbers, not quoted strings.

lat without lon fails validation, and the Site is dropped from the payload with no error. The Project still returns processed — that pickup or drop-off is simply missing. Sending neither coordinates nor full_address does the same thing.

Projects read only the pickup and drop_off waypoints. Orders also read staging.

Aim at where trucks stop

The geofence is a circle centered on the exact lat/lon you send. Point it at the scale house, the gate, or the stockpile. A mailing address or a parcel centroid is the most common reason a fence never triggers. The coordinates land somewhere a truck never parks, so no GPS ping falls inside the circle.

Coordinates beat addresses

Send lat/lon whenever your source system has them. When a Site arrives with full_address and no coordinates, Tread geocodes the address and accepts the result only when Google returns a ROOFTOP or GEOMETRIC_CENTER match. Rural quarry and job-site addresses often resolve to RANGE_INTERPOLATED or APPROXIMATE. Tread rejects those on purpose, because a fence in the wrong place is worse than no fence. The Site is created with no coordinates and no geofence. Two more things worth knowing about the fallback:

Geocoding runs only when both lat and lon are empty. It never overwrites coordinates you sent.
An address of UNDEFINED or UNKNOWN is skipped rather than geocoded. Integrations send these as placeholders.

Keep full_address even when you send coordinates. Tread uses it as the geofence label and for display.

Set the default radius first

With coordinates present, Tread draws a circle centered on them using your company’s default radius. Confirm that default before your first import.

Open Settings → Configuration

Find the Geofence Creation panel. See Platform Configurations for the rest of the settings on this page.

Set Auto Geofence Type to Circle

None stores no default radius, so no geofence gets created — no matter how good your coordinates are. The Radius field only appears once the type is Circle.

The Geofence Creation setting with Auto Geofence Type set to Circle and the Radius field highlighted

Size the radius to the site

The field displays feet or meters based on your company’s unit setting. The API always uses meters.

Site kind	Typical radius
Large pit, quarry, or yard	100–150 m (330–500 ft)
Plant or depot	75–100 m (250–330 ft)
Tight urban drop-off	~50 m (165 ft)

Cover the working area plus GPS drift. Keep circles of neighboring Sites from overlapping, or arrival and departure attribution gets ambiguous.

Override the radius on one Site

Add a next_billion_geofence object to a Site to override the company default. circle_radius is in meters and must be greater than zero. circle_center defaults to the Site’s lat/lon when you leave it out.

{
  "waypoint": "pickup",
  "external_id": "SITE-QUARRY-1",
  "name": "Quarry Rd Scale House",
  "lat": 39.812345,
  "lon": -105.087654,
  "next_billion_geofence": {
    "geofence": {
      "name": "Quarry Rd",
      "type": "circle",
      "circle_radius": 120
    }
  }
}

type accepts circle or polygon. Polygons take a geojson object instead of a radius.

A malformed next_billion_geofence drops the whole Site, silently, exactly like bad coordinates. Leave the key off entirely when you aren’t overriding the default.

Coordinates are set once

A Site that matches an existing record is reused as-is. Tread matches on external_id, or on name when the stored Site has no external_id. New lat/lon values in a later payload are ignored. Get coordinates right on the first import. Corrections after that go through the Tread app or the REST Site endpoint, not the Importer APIs.

Verify after import

A 202 Accepted and a processed state don’t prove the Site landed. Check the map instead.

The Site draws a circle on the Live Map.
Loads running through it log arrival and departure events.
A Site that appears on the Project but draws no circle means its coordinates or the default radius failed.

Common pitfalls

One coordinate without the other drops the Site. No error surfaces on the import record. Send both or neither.
Auto Geofence Type set to None means no geofence. Perfect coordinates still produce nothing.
Mailing addresses put the fence in the wrong place. Use the scale house, gate, or stockpile.
Address-only Sites often get no coordinates. Anything less accurate than GEOMETRIC_CENTER is rejected, which leaves the Site with no fence.
Re-importing doesn’t fix coordinates. Matched Sites keep the values they were created with.
Overlapping circles confuse attribution. Tighten the radius or switch to a polygon.

Importer APIs — the /ingest/projects and /ingest/orders payloads
Sites & Geofences — geofence types, timers, and auto-end behavior
Platform Configurations — the company-wide geofence defaults
Onboarding: Sites — setting up Sites in the app
Paving & Moving Geofences — fences that travel with the work

​Send lat and lon together

​Aim at where trucks stop

​Coordinates beat addresses

​Set the default radius first

​Override the radius on one Site

​Coordinates are set once

​Verify after import

​Common pitfalls

​Related

Send lat and lon together

Aim at where trucks stop

Coordinates beat addresses

Set the default radius first

Override the radius on one Site

Coordinates are set once

Verify after import

Common pitfalls

Related