Precip - Hyperlocal Weather Data API
Setup
Read your credentials from ~/.gooseworks/credentials.json:
export GOOSEWORKS_API_KEY=$(python3 -c "import json;print(json.load(open('$HOME/.gooseworks/credentials.json'))['api_key'])")
export GOOSEWORKS_API_BASE=$(python3 -c "import json;print(json.load(open('$HOME/.gooseworks/credentials.json')).get('api_base','https://api.gooseworks.ai'))")
If ~/.gooseworks/credentials.json does not exist, tell the user to run: npx gooseworks login
All endpoints use Bearer auth: -H "Authorization: Bearer $GOOSEWORKS_API_KEY"
Access hyperlocal weather data including precipitation, temperature, wind, soil conditions, and more.
Capabilities
- Last 48 Hours Precipitation Data: Total precipitation in the last 48 hours for the given location(s)
- Air Temperature: Hourly near-surface air temperature in Celsius (°C)
- Hourly Soil Moisture: Hourly soil moisture percentage relative to holding capacity at 0-10cm depth
- Wind Direction: Hourly wind direction in compass degrees (0-360)
- Daily Precipitation Data: Returns comprehensive daily precipitation data for the given time range and location(s)
- Wind Gusts: Hourly wind gust speed in meters per second (m/s)
- Recent Rain Event: Returns detailed information about the most recent precipitation event for the given location(s), including total amounts, precipitation type (rain/snow), timing, and how long ago it occurred
- Map Layer Tiles: Map tiles compatible with most web mapping or GIS tools
- Wind Speed: Hourly near-surface wind speed in meters per second (m/s)
- Cloud Cover: Hourly cloud cover fraction (0-1, where 0 is clear and 1 is overcast)
- Soil Temperature: Hourly soil temperature data at 0-10cm depth in Celsius (°C)
- Specific Humidity: Hourly specific humidity (kg/kg)
- Hourly Precipitation Data: Returns comprehensive hourly precipitation data for the given time range and location(s)
- Daily Soil Moisture: Daily soil moisture percentage relative to holding capacity at 0-10cm depth
- Embeddable HTML UI: Returns a complete, HTML page displaying comprehensive weather data for a specific location
- Solar Radiation: Hourly downward short-wave radiation flux in watts per square meter (W/m²)
- Relative Humidity: Hourly relative humidity as a percentage (0-100%)
Usage
Last 48 Hours Precipitation Data
Total precipitation in the last 48 hours for the given location(s).
Parameters:
- longitude* (string)
- latitude* (string)
- timeZoneId (string)
- format (string)
curl -s -X POST $GOOSEWORKS_API_BASE/v1/proxy/orthogonal/run \
-H "Authorization: Bearer $GOOSEWORKS_API_KEY" \
-H "Content-Type: application/json" \
-d '{"api":"precip","path":"/api/v1/last-48","query":{"latitude":"37.7749","longitude":"-122.4194"}}'
Air Temperature
Hourly near-surface air temperature in Celsius (°C)
Parameters:
- start* (string)
- end* (string)
- longitude* (string) - Comma-separated list of longitude coordinates (WGS84)
- latitude* (string) - Comma-separated list of latitude coordinates (WGS84)
- timeZoneId (string) - IANA timezone identifier for localizing timestamps
- format (string) - Output format:
geojson,jsonorcsv
curl -s -X POST $GOOSEWORKS_API_BASE/v1/proxy/orthogonal/run \
-H "Authorization: Bearer $GOOSEWORKS_API_KEY" \
-H "Content-Type: application/json" \
-d '{"api":"precip","path":"/api/v1/temperature-hourly","query":{"latitude":"37.7749","longitude":"-122.4194","start":"2024-01-01","end":"2024-01-02"}}'
Hourly Soil Moisture
Hourly soil moisture percentage relative to holding capacity at 0-10cm depth
Parameters:
- start* (string)
- end* (string)
- longitude* (string)
- latitude* (string)
- timeZoneId (string)
- format (string)
curl -s -X POST $GOOSEWORKS_API_BASE/v1/proxy/orthogonal/run \
-H "Authorization: Bearer $GOOSEWORKS_API_KEY" \
-H "Content-Type: application/json" \
-d '{"api":"precip","path":"/api/v1/soil-moisture-hourly","query":{"latitude":"37.7749","longitude":"-122.4194","start":"2024-01-01","end":"2024-01-02"}}'
Wind Direction
Hourly wind direction in compass degrees (0-360)
Parameters:
- start* (string)
- end* (string)
- longitude* (string) - Comma-separated list of longitude coordinates (WGS84)
- latitude* (string) - Comma-separated list of latitude coordinates (WGS84)
- timeZoneId (string) - IANA timezone identifier for localizing timestamps
- format (string) - Output format:
geojson,jsonorcsv
curl -s -X POST $GOOSEWORKS_API_BASE/v1/proxy/orthogonal/run \
-H "Authorization: Bearer $GOOSEWORKS_API_KEY" \
-H "Content-Type: application/json" \
-d '{"api":"precip","path":"/api/v1/wind-direction-hourly","query":{"latitude":"37.7749","longitude":"-122.4194","start":"2024-01-01","end":"2024-01-02"}}'
Daily Precipitation Data
Returns comprehensive daily precipitation data for the given time range and location(s). Each day includes precipitation amount, type (rain/snow/mixed), probability (for forecasts), and data source. Seamlessly combines historical observations with forecast data depending on the requested time range.
Parameters:
- start* (string)
- end* (string)
- longitude* (string)
- latitude* (string)
- timeZoneId (string)
- format (string)
curl -s -X POST $GOOSEWORKS_API_BASE/v1/proxy/orthogonal/run \
-H "Authorization: Bearer $GOOSEWORKS_API_KEY" \
-H "Content-Type: application/json" \
-d '{"api":"precip","path":"/api/v1/daily","query":{"latitude":"37.7749","longitude":"-122.4194","start":"2024-01-01","end":"2024-01-31"}}'
Wind Gusts
Hourly wind gust speed in meters per second (m/s)
Parameters:
- start* (string)
- end* (string)
- longitude* (string) - Comma-separated list of longitude coordinates (WGS84)
- latitude* (string) - Comma-separated list of latitude coordinates (WGS84)
- timeZoneId (string) - IANA timezone identifier for localizing timestamps
- format (string) - Output format:
geojson,jsonorcsv
curl -s -X POST $GOOSEWORKS_API_BASE/v1/proxy/orthogonal/run \
-H "Authorization: Bearer $GOOSEWORKS_API_KEY" \
-H "Content-Type: application/json" \
-d '{"api":"precip","path":"/api/v1/wind-speed-gust-hourly","query":{"latitude":"37.7749","longitude":"-122.4194","start":"2024-01-01","end":"2024-01-02"}}'
Recent Rain Event
Returns detailed information about the most recent precipitation event for the given location(s), including total amounts, precipitation type (rain/snow), timing, and how long ago it occurred.
Parameters:
- longitude* (string)
- latitude* (string)
- timeZoneId (string)
- format (string)
curl -s -X POST $GOOSEWORKS_API_BASE/v1/proxy/orthogonal/run \
-H "Authorization: Bearer $GOOSEWORKS_API_KEY" \
-H "Content-Type: application/json" \
-d '{"api":"precip","path":"/api/v1/recent-rain","query":{"latitude":"37.7749","longitude":"-122.4194"}}'
Map Layer Tiles
Map tiles compatible with most web mapping or GIS tools. Software such as Mapbox, Google Maps, ArcGIS, Leaflet, OpenLayers or QGIS will require an x/y/z url eg https://api.precip.ai/api/v1/map/last-48/ImageServer/tile/{z}/{y}/{x}. See the examples for more details.
Parameters:
- time (string)
curl -s -X POST $GOOSEWORKS_API_BASE/v1/proxy/orthogonal/run \
-H "Authorization: Bearer $GOOSEWORKS_API_KEY" \
-H "Content-Type: application/json" \
-d '{"api":"precip","path":"/api/v1/map/precipitation/ImageServer/tile/5/12/10"}'
Wind Speed
Hourly near-surface wind speed in meters per second (m/s)
Parameters:
- start* (string)
- end* (string)
- longitude* (string) - Comma-separated list of longitude coordinates (WGS84)
- latitude* (string) - Comma-separated list of latitude coordinates (WGS84)
- timeZoneId (string) - IANA timezone identifier for localizing timestamps
- format (string) - Output format:
geojson,jsonorcsv
curl -s -X POST $GOOSEWORKS_API_BASE/v1/prox