Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/samgutentag/bcycle-map/llms.txt

Use this file to discover all available pages before exploring further.

The /geocode endpoint proxies free-text address queries to the Google Maps Geocoding API, keeping the GOOGLE_MAPS_API_KEY secret server-side and out of the web bundle. It is used by the Nearby Stations Sheet when the user denies browser geolocation permission or geolocation is unavailable — the user types an address, the frontend debounces the input and calls this endpoint to resolve coordinates.

​
Endpoint

GET /api/geocode

​
Query parameters

​
q
string
required
The address or place name to geocode. Must be between 1 and 200 characters after trimming whitespace.Example: Stearns Wharf, Santa Barbara, CA

​
Response

​
Success — 200 OK

Returned when Google resolves the query to at least one result. Response includes Cache-Control: max-age=300.
​
lat
number
required
Latitude of the best-match result’s geometry centroid.
​
lng
number
required
Longitude of the best-match result’s geometry centroid.
​
formatted
string
required
Google’s formatted_address string for the top result, e.g. "Stearns Wharf, Santa Barbara, CA 93101, USA". Falls back to the original query string if Google does not return a formatted address.

​
Error responses

All error bodies follow { "error": "<code>" }.
HTTP Statuserror valueMeaning
200ZERO_RESULTSGoogle understood the query but found no matching addresses. The HTTP status is still 200; check the error field.
400INVALIDq is empty, exceeds 200 characters, or the request body is malformed.
429OVER_QUOTAThe Google Maps API key has exceeded its daily or per-second quota (OVER_QUERY_LIMIT or OVER_DAILY_LIMIT returned upstream).
500INVALIDGOOGLE_MAPS_API_KEY is not set in Worker secrets. The endpoint degrades gracefully to INVALID rather than exposing a 500.
502INVALIDThe upstream Google API request failed (network error, non-2xx response, or unexpected response body).

​
Example requests

# Successful geocode
curl "https://bcycle-map-read-api.developer-95b.workers.dev/api/geocode?q=Stearns+Wharf+Santa+Barbara+CA"

# Query with no results
curl "https://bcycle-map-read-api.developer-95b.workers.dev/api/geocode?q=xyzzy+nowhere+land"

​
Example responses

Success: 
{
  "lat": 34.4094,
  "lng": -119.6857,
  "formatted": "Stearns Wharf, Santa Barbara, CA 93101, USA"
}
Zero results: 
{
  "error": "ZERO_RESULTS"
}
Quota exceeded: 
{
  "error": "OVER_QUOTA"
}
This endpoint requires GOOGLE_MAPS_API_KEY to be configured as a Worker secret. Without it every request returns { "error": "INVALID" } with HTTP 500. The same API key powers the travel-times computation pipeline, so exhausting the quota would affect both features.
The frontend debounces address input by approximately 400 milliseconds and cancels in-flight requests when a new keystroke arrives (using AbortSignal). This debounce is load-bearing for quota management — avoid calling this endpoint in a tight loop or without debouncing in custom integrations.

Build docs developers (and LLMs) love

Get started for freeTalk to us