Geocoding and places API
Forward geocoding turns a place name into coordinates. Reverse geocoding turns a coordinate into the nearest address. A places endpoint returns nearby locations for a coordinate.
These are the smallest endpoints on the platform and they exist because almost everything else takes a latitude and longitude. If your input is a city name or a postal code, this is the step in front of the weather, air quality and soil endpoints.
Endpoints
3 endpoints. Request and response examples for each one are in the full reference.
| Method | Endpoint | What it returns |
|---|---|---|
| GET | /location/geocodeapi.aquabotany.com |
Resolve a place name to coordinates. |
| GET | /location/reverse-geocodeapi.aquabotany.com |
Resolve a coordinate to the nearest address. |
| GET | /places/gas-stationsapi.aquabotany.com |
Nearest gas stations (the Kwik Trip / Kwik Star network) to a coordinate. Locations only: id, name, distance, coordinates, address, and phone. No fuel price fields. Also reachable at its original path, /places/kwik-trip , which remains a live alias. |
Where the data comes from
| Data | Published by |
|---|---|
| Forward and reverse geocoding | Public geocoding services, see the full reference per endpoint |
| Nearby locations | Published location data for the named network |
Getting started
Every endpoint is JSON over HTTPS and takes one API key in an x-api-key header. There is no SDK to install and no OAuth dance.
curl "https://api.aquabotany.com/v1/location/geocode?name=Minneapolis" \
-H "x-api-key: $BBL_API_KEY"Quickstart, authentication and errors and rate limits are documented in the reference. Keys are issued from the Bottle Blue dashboard.
Common questions
Do I need geocoding to use the rest of the API?
Only if your input is a name rather than a coordinate. The weather, environment and soil endpoints all take a latitude and longitude, so a typical flow is one geocode call followed by however many data calls you need for that point.
Is there an endpoint that takes a place name directly?
A few have one. Elevation, for example, has both a coordinate form and a by-place form. Where that exists it is documented as a separate endpoint in the full reference, so you can skip the geocoding step.
What does reverse geocoding return?
The nearest address to the coordinate you pass. It is the right call when you have a device position or a map click and need something a person can read.