Skip to main content
Sites use coordinates for physical location and can include a postal address when one is known or can be resolved. Organisations use postal addresses only.

​
Creating sites

When you create a site, provide at least one of coordinates or address:
  • Use coordinates when you already know the exact latitude/longitude.
  • Use address when you want Cula to geocode a postal address.
  • Use both when you want Cula to validate that the coordinates and address point to the same place.
Address-only create request
{
  "external_id": "GC-VND-ACKJAM",
  "name": "Ackerman Farms (James)",
  "address": {
    "street": "123 Farm Road",
    "city": "Dickinson",
    "postcode": "58601",
    "country": "United States",
    "country_code": "US"
  },
  "managed_by_site": { "external_id": "GC-SITE-REFINERY" },
  "organisation": { "external_id": "GC-ORG-ACKJAM" }
}
If you submit only coordinates, the API stores those coordinates without a geocoding round trip. If you submit an address, the API geocodes it first and stores the resolved coordinates and canonical address. If you submit both, the API rejects the request when the supplied coordinates and geocoded address do not agree. The create response returns the resolved site so you can verify what was saved:
Site create response
{
  "id": "ste_01kqzcjrpyf27tge7875y20mmr",
  "external_id": "GC-VND-ACKJAM",
  "name": "Ackerman Farms (James)",
  "timezone": "America/Chicago",
  "coordinates": {
    "lat": 46.8792,
    "long": -102.7896
  },
  "address": {
    "street": "123 Farm Road",
    "city": "Dickinson",
    "postcode": "58601",
    "country": "United States",
    "country_code": "US"
  }
}

​
Filtering sites by address

GET /v1/sites accepts an address query parameter for free-form address search. The server geocodes the string before querying sites. It then filters by the resolved components:
  • country_code must match exactly.
  • city and postcode match as case-insensitive substrings when the geocoder resolves them.
  • street is returned for transparency but is not used for matching.
The response includes geocoded_address when an address filter was supplied. Use it to check what the server matched against. 
curl "https://api.demo.cula.earth/tracking/v1/sites?address=Friedrichstrasse%201%2C%2010117%20Berlin%2C%20Germany" \
  -H "Authorization: Bearer $CULA_ACCESS_TOKEN" \
  -H "Cula-Organisation-Id: $CULA_ORGANISATION_ID"
If the address cannot be geocoded, the API returns a validation error. Refine the address or filter by coordinates instead.

​
Organisation addresses

Organisations use an optional postal address. Organisation addresses do not represent a tracked physical processing location, so they do not include coordinates and are not used for distance or transport calculations.