03 / Integration guide
Your first nearby lookup
Using the phone app needs no coding. Connecting dispatch software requires a developer to send HTTPS requests from your server. Keep the keys there and authenticate each driver.
1. Try the test location
Set LOCATION_CODES_API_KEY on your server to your test key, then run this Python example. Test coordinates are latitude 28, longitude −81. Expect DEMO-1234.
import os, time, requests
base = "https://locationcode.org/api/company-test/v1"
headers = {"Authorization": "Bearer " + os.environ["LOCATION_CODES_API_KEY"]}
fix = {"driver_id": "driver-1", "device_id": "phone-1",
"latitude": 28, "longitude": -81, "accuracy_m": 5,
"captured_at": int(time.time())}
r = requests.post(base + "/nearby", json=fix, headers=headers, timeout=15)
r.raise_for_status()
print(len(r.json()["codes"]))2. Look up codes on arrival
For live drivers, use the live key and the base path /api/company/v1. Send actual coordinates, accuracy in meters (15 or better), and a Unix timestamp in seconds from the last minute. An empty codes list is a successful lookup. Keep location and keypad values out of logs.
3. Save a code and recover a retry
POST to /codes with the same GPS fields plus code, request_id (one UUID per save), visibility (private or shared), at_keypad and authorized_to_share. Ask the driver for both confirmations. Private is the default. After an uncertain live save, GET /submissions/{request_id} before retrying. Keep the original ID and payload.
4. Troubleshoot a request
401: verify the key and test/live URL. 403: check company sharing permissions and warehouse restrictions. 409: check submission status. 422: check GPS freshness, accuracy, field names and confirmations. 429: slow down and follow Retry-After. For support send your request ID and time to support@locationcode.org.