API Reference
Build fishing apps, integrate real-time hatch data, water conditions, and species intelligence into your platform. 12 route groups, 40+ endpoints.
https://www.fishtranslator.com/api
🔑 Authentication
Bearer Token
Authenticated endpoints require a JWT token obtained via /api/auth/login. Include the token in the Authorization header:
Authorization: Bearer <your-jwt-token>
Most read endpoints are public. Write operations (logging catches, updating profiles) require authentication. Endpoints marked AUTH require a valid token. Endpoints marked OPT accept an optional token for enhanced responses.
POST
/api/auth/register
Public
Register a new user account.
| Parameter | Type | Required | Description |
|---|---|---|---|
| string | Yes | User email address | |
| password | string | Yes | Password (min 6 characters) |
| displayName | string | No | Public display name |
Example Request
curl -X POST https://www.fishtranslator.com/api/auth/register \
-H "Content-Type: application/json" \
-d '{"email":"angler@example.com","password":"tightlines","displayName":"BassMaster"}'
POST
/api/auth/login
Public
Authenticate and receive a JWT token.
| Parameter | Type | Required | Description |
|---|---|---|---|
| string | Yes | Registered email | |
| password | string | Yes | Account password |
Example Response
{
"token": "eyJhbGciOiJIUzI1NiIs...",
"user": { "id": 42, "email": "angler@example.com", "displayName": "BassMaster" }
}
GET
/api/auth/profile
Auth
Get the authenticated user's profile.
PUT
/api/auth/profile
Auth
Update profile fields (displayName, avatar, preferences).
GET
/api/auth/verify
Auth
Verify a JWT token is valid. Returns
{ valid: true, userId, email }.⏱ Rate Limits
Current Limits
- Public endpoints: 60 requests/minute per IP
- Authenticated endpoints: 120 requests/minute per user
- External API proxies (Weather, Water): 30 requests/minute (NWS/USGS rate limits apply)
- AI Coaching: 10 requests/minute (QwenBridge capacity)
Rate limit headers are included in responses: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset.
🐟 Species
57-species database with habitat, feeding patterns, fishing techniques, and state records.
GET
/api/species
Public
List all species. Supports pagination and filtering by category.
| Parameter | Type | Required | Description |
|---|---|---|---|
| category | string | No | Filter by category (e.g. "bass", "trout", "catfish") |
| q | string | No | Search by name or alias |
| page | integer | No | Page number (default: 1) |
| limit | integer | No | Results per page (default: 50) |
Example Request
curl https://www.fishtranslator.com/api/species?category=bass&limit=10
GET
/api/species/search?q={query}
Public
Quick search by name, scientific name, or alias. Returns top 20 matches.
GET
/api/species/:id
Public
Full species profile: habitat, feeding, techniques, regulations, state records.
Example Request
curl https://www.fishtranslator.com/api/species/largemouth_bass
📍 Locations
Nationwide fishing location database with species lists, regulations, and GPS coordinates.
GET
/api/locations
Public
List all fishing locations. Filter by state, type, or search query.
| Parameter | Type | Required | Description |
|---|---|---|---|
| state | string | No | State name (e.g. "Ohio") |
| type | string | No | lake, river, reservoir, pond, creek |
| q | string | No | Search by location name |
| page | integer | No | Page number (default: 1) |
| limit | integer | No | Results per page (default: 50) |
GET
/api/locations/detail/:id
Public
Full location profile with species list, access info, and regulations.
GET
/api/locations/nearest
Public
Find the nearest fishing locations to a GPS coordinate.
| Parameter | Type | Required | Description |
|---|---|---|---|
| lat | number | Yes | Latitude |
| lng | number | Yes | Longitude |
| limit | integer | No | Number of results (default: 5) |
Example Request
curl "https://www.fishtranslator.com/api/locations/nearest?lat=40.05&lng=-83.95&limit=5"
GET
/api/locations/:state
Public
All fishing locations in a state.
GET
/api/locations/regulations/:state
Public
State fishing regulations (bag limits, size limits, seasons, license info).
🎣 Catches
Log catches, track personal bests, earn XP, and compete on leaderboards.
POST
/api/catches
Optional Auth
Log a new catch. Supports photo upload via multipart form data. Automatically checks for trophies, personal bests, and awards XP.
| Parameter | Type | Required | Description |
|---|---|---|---|
| speciesId | string | Yes | Species identifier (e.g. "largemouth_bass") |
| locationId | string | No | Location from database |
| customLocation | string | No | Free-text location name |
| weight | number | No | Weight in lbs |
| length | number | No | Length in inches |
| baitUsed | string | No | Bait or lure used |
| technique | string | No | Fishing technique |
| waterTemp | number | No | Water temperature (F) |
| photo | file | No | Photo (JPEG/PNG/WebP, max 10MB) |
| notes | string | No | Additional notes |
Example Request
curl -X POST https://www.fishtranslator.com/api/catches \
-H "Authorization: Bearer <token>" \
-F "speciesId=largemouth_bass" \
-F "weight=6.5" \
-F "baitUsed=Senko green pumpkin" \
-F "photo=@mybass.jpg"
GET
/api/catches/:userId
Public
User's catch log with pagination. Filter by species or location.
GET
/api/catches/:userId/stats
Public
User statistics: total catches, unique species, biggest catch, XP, level, mastery, achievements.
GET
/api/catches/leaderboard/global
Public
Global leaderboard ranked by weight. Optionally filter by species.
🧠 Coaching
AI-powered fishing coaching using the CAST methodology (Conditions, Activity, Select, Technique).
GET
/api/coaching/tip
Public
Get an AI-generated fishing tip based on current conditions. Falls back to static tips if AI is unavailable.
| Parameter | Type | Required | Description |
|---|---|---|---|
| species | string | No | Target species |
| location | string | No | Fishing location name |
| season | string | No | spring, summer, fall, winter |
| waterTemp | number | No | Water temp in F |
POST
/api/coaching/chat
Public
Conversational AI fishing coach. Ask any fishing question and get expert advice.
| Parameter | Type | Required | Description |
|---|---|---|---|
| question | string | Yes | Your fishing question |
| species | string | No | Target species for context |
| location | string | No | Location for context |
| season | string | No | Current season |
| waterTemp | number | No | Water temp in F |
Example Request
curl -X POST https://www.fishtranslator.com/api/coaching/chat \
-H "Content-Type: application/json" \
-d '{"question":"What color crankbait for stained water?","species":"largemouth_bass","waterTemp":62}'
GET
/api/coaching/cast
Public
Full CAST breakdown (Conditions, Activity, Select, Technique) for given parameters.
🪲 Hatch / Food Chain
The core differentiator: real-time hatch predictions and food chain analysis.
GET
/api/hatch/predict
Public
Predict currently active insect hatches based on weather and water conditions.
| Parameter | Type | Required | Description |
|---|---|---|---|
| waterTemp | number | No | Water temperature (F) |
| airTemp | number | No | Air temperature (F) |
| pressure | number | No | Barometric pressure (inHg) |
| pressureTrend | string | No | rising, falling, stable |
| cloudCover | string | No | clear, partly_cloudy, overcast |
| wind | string | No | calm, light, moderate, strong |
| region | string | No | Geographic region (default: midwest) |
Example Request
curl "https://www.fishtranslator.com/api/hatch/predict?waterTemp=58&airTemp=65&pressure=29.9&pressureTrend=falling&cloudCover=overcast"
GET
/api/hatch/foodchain
Public
Full food chain analysis: weather drives bugs, bugs feed fish, fish tell you what bait to throw. Returns chain score, active hatches, bait recommendations, and solunar data.
| Parameter | Type | Required | Description |
|---|---|---|---|
| lat | number | No | Latitude |
| lng | number | No | Longitude |
| species | string | No | Target species for tailored recommendations |
| waterTemp | number | No | Water temperature (F) |
| pressure | number | No | Barometric pressure (inHg) |
| region | string | No | Geographic region |
GET
/api/hatch/solunar
Public
Moon phase, sunrise/sunset, and major/minor feeding periods for a location.
GET
/api/hatch/calendar/:region
Public
Regional insect hatch calendar by month. Which bugs emerge when.
GET
/api/hatch/insects
Public
Full insect/forage species database. Filter by taxonomic order or region.
📈 Forecast
Predictive fishing scores using solunar data, food chain analysis, and seasonal patterns.
GET
/api/forecast/best-now
Public
Rank nearby locations by current fishing activity score. Best places to fish right now.
| Parameter | Type | Required | Description |
|---|---|---|---|
| lat | number | No | Latitude (centers search) |
| lng | number | No | Longitude |
| radius | number | No | Search radius in miles (default: 100) |
| species | string | No | Filter by species |
| limit | integer | No | Number of results (default: 10) |
GET
/api/forecast/week
Public
Best day to fish this week. 7-day solunar forecast with ratings and tips.
GET
/api/forecast/solunar-calendar
Public
Full-month solunar calendar with daily moon phases and fishing ratings.
⛅ Weather
Fishing-relevant weather from the National Weather Service API.
GET
/api/weather
Public
Current weather and 24-hour hourly forecast with fishing advice. Source: NWS api.weather.gov.
| Parameter | Type | Required | Description |
|---|---|---|---|
| lat | number | Yes | Latitude |
| lng | number | Yes | Longitude |
Example Request
curl "https://www.fishtranslator.com/api/weather?lat=40.05&lng=-83.95"
🌊 Water Conditions
Real-time water data from USGS gauges: temperature, flow, dissolved oxygen, turbidity, pH.
GET
/api/water/:siteId
Public
Current water conditions from a USGS gauge site. Returns water temp, discharge, gauge height, dissolved oxygen, turbidity, pH, conductance, plus fishing advice.
Example Request
curl https://www.fishtranslator.com/api/water/03226800
# Scioto River at Columbus, OH
GET
/api/water/search/:state
Public
Find USGS gauge stations in a state. Returns site IDs, names, coordinates, and current water temps.
Example Request
curl https://www.fishtranslator.com/api/water/search/OH
🍳 Recipes
Fish recipes matched to species, difficulty level, and cooking method.
GET
/api/recipes
Public
All recipes. Filter by species, tag, difficulty, or search query.
GET
/api/recipes/:id
Public
Full recipe: ingredients, steps, cook time, nutrition, and paired species.
GET
/api/recipes/for/:speciesId
Public
Recipes for a specific fish species.
📅 Calendar
Seasonal fishing calendars by state and species.
GET
/api/calendar/seasonal/:state
Public
Monthly fishing calendar for a state: what species to target each month, with quality ratings.
Example Request
curl https://www.fishtranslator.com/api/calendar/seasonal/Ohio
GET
/api/calendar/species/:speciesId
Public
When and where to catch a specific species. Grouped by season, sorted by trophy waters first.
Apply for API Access
Want to build on top of Fish Translator data? Apply for an API key and get higher rate limits, webhook support, and priority access to new endpoints.
📱 Social
Shareable catch cards, public feed, and leaderboards.