action dodo_get_villagers {
  label: "Villagers"
  description: "This endpoint retrieves villager information from the entire *Animal Crossing* series, with the option to filter by species, personality, game, and/or birthday. Filters use the AND operator (e.g. asking for villagers who have species `frog` and personality `smug` will return all smug frogs). Note that villagers only include the animals that act as residents. Special characters, such as Tom Nook and Isabelle, are not accessed through this endpoint."
  provider: dodo
  method: GET
  path: "/villagers"
  encoding: json
  input: {
    type: "object"
    properties: {
      "Accept-Version": {
        type: "string"
      }
      "X-API-KEY": {
        type: "string"
        format: "uuid"
      }
      birthday: {
        type: "string"
      }
      birthmonth: {
        type: "string"
      }
      excludedetails: {
        type: "string"
      }
      game: {
        type: "array"
        items: {
          type: "string"
          enum: ["DNM", "AC", "E_PLUS", "WW", "CF", "NL", "WA", "NH", "FILM", "HHD", "PC"]
        }
      }
      name: {
        type: "string"
      }
      nhdetails: {
        type: "string"
      }
      personality: {
        type: "string"
        enum: ["lazy", "jock", "cranky", "smug", "normal", "peppy", "snooty", "sisterly"]
      }
      species: {
        type: "string"
        enum: ["alligator", "anteater", "bear", "bird", "bull", "cat", "cub", "chicken", "cow", "deer", "dog", "duck", "eagle", "elephant", "frog", "goat", "gorilla", "hamster", "hippo", "horse", "koala", "kangaroo", "lion", "monkey", "mouse", "octopus", "ostrich", "penguin", "pig", "rabbit", "rhino", "sheep", "squirrel", "tiger", "wolf"]
      }
      thumbsize: {
        type: "integer"
      }
    }
    required: ["Accept-Version", "X-API-KEY"]
    additionalProperties: false
  }
  output: {
    type: "array"
    items: {
      type: "object"
      properties: {
        alt_name: {
          type: "string"
          description: "A previous name for the villager. A very small number of villagers changed names between earlier games, such as Sally being known as Hazel in the original game."
        }
        appearances: {
          type: "array"
          description: "List of official media the villager appeared in. `DNM` is *Doubutsu no Mori* for the Nintendo 64 (Japan-exclusive); `AC` is *Animal Crossing* for GameCube; `E_PLUS` is *Doubutsu no Mori e+* for GameCube (expanded port of AC, Japan-exclusive); `WW` is *Wild World* for the DS; `CF` is *City Folk* for Wii; `NL` is *New Leaf* for 3DS; `WA` is *Welcome amiibo*, the *New Leaf* expansion; `NH` is *New Horizons* for Switch; `FILM` is the *Doubutsu no Mori* Japan-exclusive film; `HHD` is *Happy Home Designer* for the Wii; and `PC` is *Pocket Camp* for mobile."
          items: {
            type: "string"
            enum: ["DNM", "AC", "E_PLUS", "WW", "CF", "NL", "WA", "NH", "FILM", "HHD", "PC"]
          }
        }
        birthday_day: {
          type: "string"
          description: "Birthday day of the villager. Note that villager birthdays were not introduced until *Wild World*. For villagers who didn't appear in *Wild World* or any later games, this field will be an empty string."
        }
        birthday_month: {
          type: "string"
          description: "Birthday month of the villager. Note that villager birthdays were not introduced until *Wild World*. For villagers who didn't appear in *Wild World* or any later games, this field will be an empty string."
        }
        clothing: {
          type: "string"
          description: "The villager's default clothing. This will be the clothing from the latest game (i.e. if the villager had varying phrases between *Wild World* and *New Horizons*, this will be the *New Horizons* clothing)."
        }
        debut: {
          type: "string"
          description: "The first *Animal Crossing* game the villager appeared in. `DNM` is *Doubutsu no Mori* for the Nintendo 64 (Japan-exclusive); `AC` is *Animal Crossing* for GameCube; `E_PLUS` is *Doubutsu no Mori e+* for GameCube (expanded port of AC, Japan-exclusive); `WW` is *Wild World* for the DS; `CF` is *City Folk* for Wii; `NL` is *New Leaf* for 3DS; `WA` is *Welcome amiibo*, the *New Leaf* expansion; `NH` is *New Horizons* for Switch; `FILM` is the *Doubutsu no Mori* Japan-exclusive film; `HHD` is *Happy Home Designer* for the Wii; and `PC` is *Pocket Camp* for mobile."
          enum: ["DNM", "AC", "E_PLUS", "WW", "CF", "NL", "WA", "NH", "FILM", "HHD", "PC"]
        }
        gender: {
          type: "string"
          description: "Gender of the villager. In *Animal Crossing*, only male and female are used."
          enum: ["Male", "Female"]
        }
        id: {
          type: "string"
          description: "The game's internal identifier for the villager. Not all villagers have IDs; villagers who appeared in any game including or after *Wild World* have a consistent ID between games."
        }
        image_url: {
          type: "string"
          description: "Image of the villager from the latest game the villager appeared in. dodo.ac is Nookipedia's CDN server."
        }
        islander: {
          type: "boolean"
          description: "Whether the villager was an island in *Animal Crossing* for GameCube. Only a small number of villagers (36) were islanders."
        }
        name: {
          type: "string"
          description: "Name of the villager."
        }
        nh_details: {
          type: "object"
          description: "An object that holds villager data specific to *New Horizons*. If the villager does not appear in *New Horizons*, this field will be set to null."
          properties: {
            catchphrase: {
              type: "string"
              description: "The default phrase a villager will use when speaking to the player."
            }
            clothing: {
              type: "string"
              description: "The default clothing that the villager wears."
            }
            clothing_variation: {
              type: "string"
              description: "The variation of the clothing (usually a color)."
            }
            fav_colors: {
              type: "array"
              description: "The villager's favorite colors (giving the villager a gift with one of their favorite colors increases friendship points)."
              items: {
                type: "string"
              }
            }
            fav_styles: {
              type: "array"
              description: "The villager's favorite clothing styles."
              items: {
                type: "string"
              }
            }
            hobby: {
              type: "string"
              description: "The villager's primary hobby, which determines most of the activities they will do around the island (e.g. education villagers will frequently read books and visit the museum). Learn more at https://nookipedia.com/wiki/Hobbies"
              enum: ["Education", "Fashion", "Fitness", "Music", "Nature", "Play"]
            }
            house_exterior_url: {
              type: "string"
              description: "A rendered model of the villager's house exterior. Note that this is not an official Nintendo asset, but a render based of the in-game model."
            }
            house_flooring: {
              type: "string"
              description: "The flooring in the villager's house."
            }
            house_interior_url: {
              type: "string"
              description: "A screenshot of the villager's house interior."
            }
            house_music: {
              type: "string"
              description: "The music in the villager's house."
            }
            house_music_note: {
              type: "string"
              description: "Any notes about the villager's music. If populated, this is usually \"Does not contain a stereo initially\", meaning that the villager's house will not play music unless provided with a stereo."
            }
            house_wallpaper: {
              type: "string"
              description: "The wallpaper in the villager's house."
            }
            icon_url: {
              type: "string"
              description: "The villager's icon of their head. See https://nookipedia.com/wiki/Category:New_Horizons_character_icons for full list."
            }
            image_url: {
              type: "string"
              description: "Image of the villager from *New Horizons*."
            }
            photo_url: {
              type: "string"
              description: "The villager's photo, received by the player after attaining a certain friendship level. See https://nookipedia.com/wiki/Category:New_Horizons_pictures for full list."
            }
            quote: {
              type: "string"
              description: "The villager's quote, as found on the back of their in-game photo."
            }
            "sub-personality": {
              type: "string"
              description: "Each personality in *New Horizons* has two sub-personalities, currently referred to as just A and B. The effect of a sub-personality is currently unknown."
              enum: ["A", "B"]
            }
          }
        }
        personality: {
          type: "string"
          description: "The villager's personality. Note that there are no official in-game personality names; these are names that are commonly used by the community. In the case of 'sisterly', other common names include 'big sis' and 'uchi'."
          enum: ["Cranky", "Jock", "Lazy", "Normal", "Peppy", "Sisterly", "Smug", "Snooty"]
        }
        phrase: {
          type: "string"
          description: "The villager's default phrase they use throughout conversation. This will be the phrase from the latest game (i.e. if the villager had varying phrases between *Wild World* and *New Horizons*, this will be the *New Horizons* quote)."
        }
        prev_phrases: {
          type: "array"
          description: "Any phrases used in previous *Animal Crossing* installations. May be empty."
          items: {
            type: "string"
          }
        }
        quote: {
          type: "string"
          description: "The villager's quote as it appears on the back of their in-game portrait item. This will be the quote from the latest game (i.e. if the villager had varying quotes between *Wild World* and *New Horizons*, this will be the *New Horizons* quote). For villagers from older games that do not have a quote, this field will be an empty string."
        }
        sign: {
          type: "string"
          description: "The villager's astrological star sign."
          enum: ["Aries", "Taurus", "Gemini", "Cancer", "Leo", "Virgo", "Libra", "Scorpio", "Sagittarius", "Capricorn", "Aquarius", "Pisces"]
        }
        species: {
          type: "string"
          description: "The villager's species."
          enum: ["Alligator", "Anteater", "Bear", "Bird", "Bull", "Cat", "Cub", "Chicken", "Cow", "Deer", "Dog", "Duck", "Eagle", "Elephant", "Frog", "Goat", "Gorilla", "Hamster", "Hippo", "Horse", "Koala", "Kangaroo", "Lion", "Monkey", "Mouse", "Octopus", "Ostrich", "Penguin", "Pig", "Rabbit", "Rhino", "Sheep", "Squirrel", "Tiger", "Wolf"]
        }
        text_color: {
          type: "string"
          description: "The HTML color code of the text of the villager's name badge that appears above their dialogue box when spoken to in-game. Note that to date, only *New Horizons* villagers have this field populated."
        }
        title_color: {
          type: "string"
          description: "The HTML color code of the background of the villager's name badge that appears above their dialogue box when spoken to in-game. Note that to date, only *New Horizons* villagers have this field populated. This field may be useful for styling, such as the accent color for a Discord embed."
        }
        url: {
          type: "string"
          description: "Link to the respective Nookipedia article."
        }
      }
    }
  }
}