{
  "openapi": "3.1.0",
  "info": {
    "title": "Tides & Tails public feeds",
    "version": "1.0.0",
    "summary": "Saltwater fishing directory data — charters, bait & tackle shops, waters, species and lures — as JSON.",
    "description": "Free to read and cite with attribution to Tides & Tails and a link to the listing URL. Do not republish phone numbers as a standalone directory. Conditions data on the site is not for navigation. Plain-English docs: https://www.tidesandtails.net/ai. Assistants can also connect through the MCP endpoint https://www.tidesandtails.net/api/mcp.",
    "termsOfService": "https://www.tidesandtails.net/terms",
    "contact": {
      "name": "Tides & Tails",
      "url": "https://www.tidesandtails.net/ai"
    },
    "license": {
      "name": "Free to read and cite with attribution to Tides & Tails (tidesandtails.net).",
      "url": "https://www.tidesandtails.net/terms"
    }
  },
  "servers": [
    {
      "url": "https://www.tidesandtails.net"
    }
  ],
  "paths": {
    "/feed/search.json": {
      "get": {
        "operationId": "searchDirectory",
        "summary": "Search charters and bait & tackle shops.",
        "description": "Flat, paginated search over the real directory listings (demo profiles are never included). All parameters are optional; an unknown enum value or a non-numeric number returns HTTP 400 with an `error` message naming the parameter. Pass `lat` and `lon` for a 'near me' search: results within `radius` miles, nearest first, each with `distanceMiles` and `distanceBasis`, plus `meta.nearestWaters`. Cached for five minutes.",
        "parameters": [
          {
            "name": "type",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "charters",
                "bait-shops",
                "all"
              ],
              "default": "all"
            },
            "description": "Which part of the directory to search."
          },
          {
            "name": "water",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Home-water slug, e.g. `destin` or `tampa-bay` (see /feed/locations.json)."
          },
          {
            "name": "town",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Case-insensitive substring of the home town."
          },
          {
            "name": "coast",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "gulf",
                "atlantic",
                "pacific"
              ]
            },
            "description": "Broad coast the water sits on."
          },
          {
            "name": "species",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Species id as used in the catalogs, e.g. `red-drum`, `speckled-trout`, `snook`."
          },
          {
            "name": "trip",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Trip-type substring, e.g. `inshore` or `offshore`. Charters only."
          },
          {
            "name": "badge",
            "in": "query",
            "required": false,
            "schema": {
              "type": "array",
              "items": {
                "type": "string",
                "enum": [
                  "verified",
                  "featured",
                  "responds-fast"
                ]
              }
            },
            "description": "Trust badge. Repeat the parameter to require several; every badge named must be present.",
            "style": "form",
            "explode": true
          },
          {
            "name": "maxPrice",
            "in": "query",
            "required": false,
            "schema": {
              "type": "number",
              "minimum": 0
            },
            "description": "Keep only listings with at least one trip package priced at or under this amount (USD). Listings with no published packages are excluded when set."
          },
          {
            "name": "q",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Free text, case-insensitive, matched against name, town, water name and description."
          },
          {
            "name": "lat",
            "in": "query",
            "required": false,
            "schema": {
              "type": "number",
              "minimum": -90,
              "maximum": 90
            },
            "description": "Caller's latitude in decimal degrees. Give `lat` and `lon` together (one without the other is a 400) to switch on near-me mode: every result gains `distanceMiles` and `distanceBasis`, only results within `radius` miles are returned, sorted nearest first, and `meta.nearestWaters` lists the closest catalog waters."
          },
          {
            "name": "lon",
            "in": "query",
            "required": false,
            "schema": {
              "type": "number",
              "minimum": -180,
              "maximum": 180
            },
            "description": "Caller's longitude in decimal degrees (negative for the western hemisphere, e.g. `-87.2`). Required whenever `lat` is given."
          },
          {
            "name": "radius",
            "in": "query",
            "required": false,
            "schema": {
              "type": "number",
              "exclusiveMinimum": 0,
              "maximum": 300,
              "default": 75
            },
            "description": "Search radius in statute miles around `lat`/`lon`. Defaults to 75; values above 300 are capped at 300; non-numeric, zero or negative is a 400. Ignored without coordinates."
          },
          {
            "name": "page",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "default": 1
            },
            "description": "1-based page number."
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 50,
              "default": 25
            },
            "description": "Results per page."
          }
        ],
        "responses": {
          "200": {
            "description": "Matching listings.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "meta",
                    "results"
                  ],
                  "properties": {
                    "meta": {
                      "type": "object",
                      "properties": {
                        "query": {
                          "type": "object",
                          "description": "The parameters as understood, defaults filled in."
                        },
                        "total": {
                          "type": "integer"
                        },
                        "page": {
                          "type": "integer"
                        },
                        "limit": {
                          "type": "integer"
                        },
                        "nearestWaters": {
                          "type": "array",
                          "maxItems": 5,
                          "items": {
                            "type": "object",
                            "required": [
                              "slug",
                              "name",
                              "state",
                              "distanceMiles",
                              "url"
                            ],
                            "properties": {
                              "slug": {
                                "type": "string"
                              },
                              "name": {
                                "type": "string"
                              },
                              "state": {
                                "type": [
                                  "string",
                                  "null"
                                ],
                                "description": "Two-letter US state."
                              },
                              "distanceMiles": {
                                "type": "number"
                              },
                              "url": {
                                "type": "string",
                                "format": "uri",
                                "description": "The water's location page on tidesandtails.net."
                              }
                            }
                          },
                          "description": "Near-me mode only. Up to 5 catalog waters closest to the caller, nearest first, regardless of `radius` — so an empty result set still says which coast is closest."
                        },
                        "generatedAt": {
                          "type": "string",
                          "format": "date-time"
                        },
                        "source": {
                          "type": "string",
                          "format": "uri"
                        },
                        "docs": {
                          "type": "string",
                          "format": "uri"
                        }
                      }
                    },
                    "results": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "required": [
                          "kind",
                          "id",
                          "name",
                          "water",
                          "url",
                          "badges"
                        ],
                        "properties": {
                          "kind": {
                            "type": "string",
                            "enum": [
                              "charter",
                              "bait-shop"
                            ]
                          },
                          "id": {
                            "type": "string",
                            "description": "Stable id, `<kind>:<water>:<name-slug>`."
                          },
                          "name": {
                            "type": "string"
                          },
                          "water": {
                            "type": "object",
                            "properties": {
                              "slug": {
                                "type": "string"
                              },
                              "name": {
                                "type": "string"
                              },
                              "coast": {
                                "type": [
                                  "string",
                                  "null"
                                ],
                                "enum": [
                                  "gulf",
                                  "atlantic",
                                  "pacific",
                                  null
                                ]
                              }
                            }
                          },
                          "town": {
                            "type": [
                              "string",
                              "null"
                            ]
                          },
                          "state": {
                            "type": [
                              "string",
                              "null"
                            ]
                          },
                          "phone": {
                            "type": [
                              "string",
                              "null"
                            ]
                          },
                          "website": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "format": "uri"
                          },
                          "marina": {
                            "type": [
                              "string",
                              "null"
                            ]
                          },
                          "address": {
                            "type": [
                              "string",
                              "null"
                            ]
                          },
                          "url": {
                            "type": "string",
                            "format": "uri",
                            "description": "The listing's own page on tidesandtails.net — for a charter that is its boat page (/charters/<water>/<boat>); link here when you cite it. Bait & tackle shops have no page of their own yet, so their `url` is the water directory page."
                          },
                          "waterUrl": {
                            "type": "string",
                            "format": "uri",
                            "description": "The water directory page the listing belongs to (/charters/<water>) — every real charter and shop on that water, with live-conditions links."
                          },
                          "badges": {
                            "type": "array",
                            "items": {
                              "type": "string",
                              "enum": [
                                "verified",
                                "featured",
                                "responds-fast"
                              ]
                            }
                          },
                          "tripTypes": {
                            "type": "array",
                            "items": {
                              "type": "string"
                            }
                          },
                          "species": {
                            "type": "array",
                            "items": {
                              "type": "string"
                            }
                          },
                          "packages": {
                            "type": "array",
                            "items": {
                              "type": "object",
                              "properties": {
                                "name": {
                                  "type": [
                                    "string",
                                    "null"
                                  ]
                                },
                                "hours": {
                                  "type": [
                                    "number",
                                    "string",
                                    "null"
                                  ]
                                },
                                "capacity": {
                                  "type": [
                                    "integer",
                                    "null"
                                  ]
                                },
                                "price": {
                                  "type": [
                                    "number",
                                    "null"
                                  ]
                                },
                                "species": {
                                  "type": "array",
                                  "items": {
                                    "type": "string"
                                  }
                                },
                                "includes": {
                                  "type": "array",
                                  "items": {
                                    "type": "string"
                                  }
                                }
                              }
                            }
                          },
                          "boat": {
                            "type": [
                              "object",
                              "null"
                            ],
                            "properties": {
                              "make": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "length": {
                                "type": [
                                  "number",
                                  "string",
                                  "null"
                                ]
                              },
                              "capacity": {
                                "type": [
                                  "integer",
                                  "null"
                                ]
                              },
                              "engine": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "toilet": {
                                "type": [
                                  "boolean",
                                  "string",
                                  "null"
                                ]
                              }
                            }
                          },
                          "included": {
                            "type": "array",
                            "items": {
                              "type": "string"
                            }
                          },
                          "description": {
                            "type": [
                              "string",
                              "null"
                            ]
                          },
                          "updatedAt": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "format": "date-time"
                          },
                          "distanceMiles": {
                            "type": "number",
                            "description": "Near-me mode only. Great-circle distance from the caller's `lat`/`lon`, statute miles, one decimal."
                          },
                          "distanceBasis": {
                            "type": "string",
                            "enum": [
                              "listing",
                              "water"
                            ],
                            "description": "Near-me mode only. What `distanceMiles` was measured to: `listing` when the business publishes its own coordinates, `water` when the distance is to the centre of its home water (the common case — treat it as 'how far to that bay', not 'how far to the dock')."
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "A parameter was invalid; `error` names it.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/feed/locations.json": {
      "get": {
        "operationId": "feed_locations",
        "summary": "All covered fisheries: coordinates, NOAA tide station, target species, towns and seasonal guidance.",
        "responses": {
          "200": {
            "description": "The feed envelope with every item.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "feed",
                    "site",
                    "generated",
                    "count",
                    "items"
                  ],
                  "properties": {
                    "feed": {
                      "type": "string"
                    },
                    "site": {
                      "type": "string",
                      "format": "uri"
                    },
                    "description": {
                      "type": "string"
                    },
                    "docs": {
                      "type": "string",
                      "format": "uri"
                    },
                    "index": {
                      "type": "string",
                      "format": "uri"
                    },
                    "license": {
                      "type": "string"
                    },
                    "generated": {
                      "type": "string",
                      "format": "date-time"
                    },
                    "count": {
                      "type": "integer"
                    },
                    "items": {
                      "type": "array",
                      "items": {
                        "type": "object"
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/feed/species.json": {
      "get": {
        "operationId": "feed_species",
        "summary": "The species catalog: habitat, water-temperature tolerances, light preferences and seasonal bait and lure guidance.",
        "responses": {
          "200": {
            "description": "The feed envelope with every item.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "feed",
                    "site",
                    "generated",
                    "count",
                    "items"
                  ],
                  "properties": {
                    "feed": {
                      "type": "string"
                    },
                    "site": {
                      "type": "string",
                      "format": "uri"
                    },
                    "description": {
                      "type": "string"
                    },
                    "docs": {
                      "type": "string",
                      "format": "uri"
                    },
                    "index": {
                      "type": "string",
                      "format": "uri"
                    },
                    "license": {
                      "type": "string"
                    },
                    "generated": {
                      "type": "string",
                      "format": "date-time"
                    },
                    "count": {
                      "type": "integer"
                    },
                    "items": {
                      "type": "array",
                      "items": {
                        "type": "object"
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/feed/lures.json": {
      "get": {
        "operationId": "feed_lures",
        "summary": "The lure database tagged by species, season, region, water clarity and light.",
        "responses": {
          "200": {
            "description": "The feed envelope with every item.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "feed",
                    "site",
                    "generated",
                    "count",
                    "items"
                  ],
                  "properties": {
                    "feed": {
                      "type": "string"
                    },
                    "site": {
                      "type": "string",
                      "format": "uri"
                    },
                    "description": {
                      "type": "string"
                    },
                    "docs": {
                      "type": "string",
                      "format": "uri"
                    },
                    "index": {
                      "type": "string",
                      "format": "uri"
                    },
                    "license": {
                      "type": "string"
                    },
                    "generated": {
                      "type": "string",
                      "format": "date-time"
                    },
                    "count": {
                      "type": "integer"
                    },
                    "items": {
                      "type": "array",
                      "items": {
                        "type": "object"
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/feed/charters.json": {
      "get": {
        "operationId": "feed_charters",
        "summary": "Charter boats and guides grouped by home water, with contact details, trip types and marketplace depth where published.",
        "responses": {
          "200": {
            "description": "The feed envelope with every item.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "feed",
                    "site",
                    "generated",
                    "count",
                    "items"
                  ],
                  "properties": {
                    "feed": {
                      "type": "string"
                    },
                    "site": {
                      "type": "string",
                      "format": "uri"
                    },
                    "description": {
                      "type": "string"
                    },
                    "docs": {
                      "type": "string",
                      "format": "uri"
                    },
                    "index": {
                      "type": "string",
                      "format": "uri"
                    },
                    "license": {
                      "type": "string"
                    },
                    "generated": {
                      "type": "string",
                      "format": "date-time"
                    },
                    "count": {
                      "type": "integer"
                    },
                    "items": {
                      "type": "array",
                      "items": {
                        "type": "object"
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/feed/bait-shops.json": {
      "get": {
        "operationId": "feed_bait_shops",
        "summary": "Verified bait & tackle shops grouped by home water, with phone, address and website.",
        "responses": {
          "200": {
            "description": "The feed envelope with every item.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "feed",
                    "site",
                    "generated",
                    "count",
                    "items"
                  ],
                  "properties": {
                    "feed": {
                      "type": "string"
                    },
                    "site": {
                      "type": "string",
                      "format": "uri"
                    },
                    "description": {
                      "type": "string"
                    },
                    "docs": {
                      "type": "string",
                      "format": "uri"
                    },
                    "index": {
                      "type": "string",
                      "format": "uri"
                    },
                    "license": {
                      "type": "string"
                    },
                    "generated": {
                      "type": "string",
                      "format": "date-time"
                    },
                    "count": {
                      "type": "integer"
                    },
                    "items": {
                      "type": "array",
                      "items": {
                        "type": "object"
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/feed/articles.json": {
      "get": {
        "operationId": "feed_articles",
        "summary": "Full text of the editorial articles.",
        "responses": {
          "200": {
            "description": "The feed envelope with every item.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "feed",
                    "site",
                    "generated",
                    "count",
                    "items"
                  ],
                  "properties": {
                    "feed": {
                      "type": "string"
                    },
                    "site": {
                      "type": "string",
                      "format": "uri"
                    },
                    "description": {
                      "type": "string"
                    },
                    "docs": {
                      "type": "string",
                      "format": "uri"
                    },
                    "index": {
                      "type": "string",
                      "format": "uri"
                    },
                    "license": {
                      "type": "string"
                    },
                    "generated": {
                      "type": "string",
                      "format": "date-time"
                    },
                    "count": {
                      "type": "integer"
                    },
                    "items": {
                      "type": "array",
                      "items": {
                        "type": "object"
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/feed/index.json": {
      "get": {
        "operationId": "feed_index",
        "summary": "Directory of every feed listed here.",
        "responses": {
          "200": {
            "description": "The feed envelope with every item.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "feed",
                    "site",
                    "generated",
                    "count",
                    "items"
                  ],
                  "properties": {
                    "feed": {
                      "type": "string"
                    },
                    "site": {
                      "type": "string",
                      "format": "uri"
                    },
                    "description": {
                      "type": "string"
                    },
                    "docs": {
                      "type": "string",
                      "format": "uri"
                    },
                    "index": {
                      "type": "string",
                      "format": "uri"
                    },
                    "license": {
                      "type": "string"
                    },
                    "generated": {
                      "type": "string",
                      "format": "date-time"
                    },
                    "count": {
                      "type": "integer"
                    },
                    "items": {
                      "type": "array",
                      "items": {
                        "type": "object"
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}