> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tread.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Site Coordinates & Geofences
> Send lat and lon on imported Sites so Tread builds a working geofence and logs arrival and departure events.
Coordinates sent through the [Importer APIs](/api-reference/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](/concepts/sites-geofences) in your `sites` array. Those two values are what Tread builds the geofence (a virtual fence around a Site) from. Send both or neither.
```json theme={null}
{
"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.
Find the **Geofence Creation** panel. See [Platform Configurations](/onboarding/platform-configurations) for the rest of the settings on this page.
**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 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.
```json theme={null}
{
"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](/workflows/track-drivers-collect-tickets).
* 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.
## Related
* [Importer APIs](/api-reference/importer-apis) — the `/ingest/projects` and `/ingest/orders` payloads
* [Sites & Geofences](/concepts/sites-geofences) — geofence types, timers, and auto-end behavior
* [Platform Configurations](/onboarding/platform-configurations) — the company-wide geofence defaults
* [Onboarding: Sites](/onboarding/master-data/sites) — setting up Sites in the app
* [Paving & Moving Geofences](/specialized/paving-geofences) — fences that travel with the work