{
 "openapi": "3.1.0",
 "info": {
  "title": "Wildlife of Everywhere API",
  "version": "1.0.0",
  "description": "Where to see mammals and birds worldwide, what lives in each park, trip reports and free field guides. Read-only, no key. Sensitive species (reptiles, amphibians, Critically Endangered, pangolins) return countries only. Species–place links are ODbL: credit Wildlife of Everywhere, GBIF.org and OpenStreetMap contributors, and cite the page URL each answer gives.",
  "license": {
   "name": "ODbL-1.0",
   "url": "https://opendatacommons.org/licenses/odbl/1-0/"
  }
 },
 "servers": [
  {
   "url": "https://wildlifeofeverywhere.com/explore/api/v1"
  }
 ],
 "paths": {
  "/search": {
   "get": {
    "operationId": "searchWildlife",
    "summary": "Find species and places by name",
    "parameters": [
     {
      "name": "q",
      "in": "query",
      "required": true,
      "schema": {
       "type": "string",
       "description": "Name, e.g. \"clouded leopard\" or \"Kinabalu\""
      }
     },
     {
      "name": "type",
      "in": "query",
      "required": false,
      "schema": {
       "type": "string",
       "description": "species, place or any",
       "enum": [
        "any",
        "species",
        "place"
       ],
       "default": "any"
      }
     },
     {
      "name": "limit",
      "in": "query",
      "required": false,
      "schema": {
       "type": "integer",
       "description": "Max results",
       "default": 10,
       "minimum": 1,
       "maximum": 50
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Matching species and places with ids",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     },
     "404": {
      "description": "Not found"
     }
    }
   }
  },
  "/species/{species}": {
   "get": {
    "operationId": "getSpecies",
    "summary": "Species facts: names, family, countries, links",
    "parameters": [
     {
      "name": "species",
      "in": "path",
      "required": true,
      "description": "Common or scientific name, or id from searchWildlife",
      "schema": {
       "type": "string"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Species",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     },
     "404": {
      "description": "Not found"
     }
    }
   }
  },
  "/species/{species}/places": {
   "get": {
    "operationId": "whereToSee",
    "summary": "Best-documented places to see a species",
    "parameters": [
     {
      "name": "species",
      "in": "path",
      "required": true,
      "description": "Common or scientific name, or id",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "country",
      "in": "query",
      "required": false,
      "schema": {
       "type": "string",
       "description": "Optional ISO3 country code, e.g. MYS"
      }
     },
     {
      "name": "limit",
      "in": "query",
      "required": false,
      "schema": {
       "type": "integer",
       "description": "Max places",
       "default": 25,
       "minimum": 1,
       "maximum": 200
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Ranked places with GBIF record counts, years, evidence and page links",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     },
     "404": {
      "description": "Not found"
     }
    }
   }
  },
  "/places/{place}": {
   "get": {
    "operationId": "getPlace",
    "summary": "Place facts: country, type, area, species count, links",
    "parameters": [
     {
      "name": "place",
      "in": "path",
      "required": true,
      "description": "Place name or id from searchWildlife",
      "schema": {
       "type": "string"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Place",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     },
     "404": {
      "description": "Not found"
     }
    }
   }
  },
  "/places/{place}/species": {
   "get": {
    "operationId": "speciesAtPlace",
    "summary": "Mammals and birds recorded at a place, most recorded first",
    "parameters": [
     {
      "name": "place",
      "in": "path",
      "required": true,
      "description": "Place name or id",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "group",
      "in": "query",
      "required": false,
      "schema": {
       "type": "string",
       "description": "mammal or bird",
       "enum": [
        "mammal",
        "bird"
       ]
      }
     },
     {
      "name": "limit",
      "in": "query",
      "required": false,
      "schema": {
       "type": "integer",
       "description": "Max species",
       "default": 50,
       "minimum": 1,
       "maximum": 1000
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Species list with counts (minimums)",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     },
     "404": {
      "description": "Not found"
     }
    }
   }
  },
  "/trips": {
   "get": {
    "operationId": "tripReports",
    "summary": "Trip reports that recorded a species and/or visited a place",
    "parameters": [
     {
      "name": "species",
      "in": "query",
      "required": false,
      "schema": {
       "type": "string",
       "description": "Species name or id"
      }
     },
     {
      "name": "place",
      "in": "query",
      "required": false,
      "schema": {
       "type": "string",
       "description": "Place name or id"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Trip reports with links and tour operators",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     },
     "404": {
      "description": "Not found"
     }
    }
   }
  },
  "/field-guide": {
   "get": {
    "operationId": "fieldGuide",
    "summary": "Free printable field guide (PDF/EPUB) and checklist for a place",
    "parameters": [
     {
      "name": "place",
      "in": "query",
      "required": true,
      "schema": {
       "type": "string",
       "description": "Place name or id"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Builder link, landing page and checklist CSV",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     },
     "404": {
      "description": "Not found"
     }
    }
   }
  }
 }
}