API reference

Basics

• Sign in with POST /auth/login and send the token on every call: Authorization: Bearer <access_token>. Tokens last 7 days; a 401 means sign in again.
• Coordinates are WGS84 (EPSG:4326) in [longitude, latitude] order, the GeoJSON convention. AGM points use separate latitude, longitude, and elevation fields.
• Errors return JSON with a detail message. Validation errors (422) list each bad field.
• Rate limits: sign-in, sign-up, password reset, join codes, and the info form allow about 10 requests a minute per address; other calls about 20 a second. Over the limit returns 429.
• API keys (for partner integrations) go in X-API-Key and are read-only: events:read covers events and rodeos, leaderboard:read covers leaderboards. Keys are issued by a site admin.
• Order does not matter. Competitors can join and submit before judges publish lines; runs are bound to the active judge lines when they are scored.

curl -s https://geolocaterodeo.com/api/v1/auth/login \
  -H 'Content-Type: application/json' \
  -d '{"email":"you@company.com","password":"…"}'
# → {"access_token":"eyJ…","token_type":"bearer","user":{…}}

How a rodeo flows

1. Organizer creates an event and its rodeos, then creates invite codes (one for competitors, one for judges).
2. Everyone joins by opening the invite link or scanning the QR. LocateIQ receives locateiq://rodeo?join=CODE&api=https://geolocaterodeo.com/api, shows the event from GET /join/{code}, signs the user in, then calls POST /join/{code}/redeem. Competitors get a run in every rodeo the code covers.
3. Judges record the dig area, judge lines, and AGM control points for each rodeo. Any order works; the first save creates the judge line set.
4. Competitors download the rodeo (dig area, AGM points, line names; never judge geometry), locate, upload their lines, and submit.
5. Judges time the run, add deductions, finalize, and release the score. Spectators follow on the public page.

Scoring

Lowest score wins. Each competitor line is matched to the judge line with the same name, tied at both ends, and the enclosed area is measured in square feet (crossings are measured piece by piece, so errors never cancel).

score = error_area_ft² × accuracy_weight
      + max(0, run_seconds − free_seconds) × points_per_second × time_weight
      + deductions

Weights, free time, points per second, and deduction buttons are set per event with PUT /events/{id}/scoring.