# Dog API
> Pull researched dog breed data into a workflow from the Dog API: over 340 breeds, each with its weight and height in both metric and imperial, how long it lives, where it came from, its coat, its temperament and ten behaviour ratings from energy to how well it does with children. Find a breed from anything a person typed, browse the catalogue by group, country, coat, size or kennel club, and ask which breeds actually fit an apartment, a household with children or an hour of walking a day. Pictures come back with the credit their licence requires, ready to embed or download, and there is a random dog fact for the steps that just need something to say. No account or API key required.
App · Misc References · 9 actions. Web page: https://docs.lodol.com/docs/integrations/dog-api
## Actions
### Download a dog picture
Download a dog picture as a file, so a later step can attach it to an email, upload it to a chat or put it in storage. Name a breed for a picture of it, pass a picture's id from an earlier step for that exact picture, or give neither for a random breed. The credit its licence requires comes back with the file. No API key required.
**Inputs**
- Breed (`breed`, text): Optional. The breed to show, named however you have it: its name, one of the names it also goes by, or the id from an earlier step. Leave it blank for a picture of a random breed.
- Picture (`picture_id`, text): Optional. The id of a picture from an earlier step, to download that exact one. Ids come back with a breed, so take one from Get a breed or Get a dog picture rather than writing it down. Overrides the breed when both are given.
- Picture size (`picture_size`, text): Optional. Which size to fetch. Medium by default, which is the one to put in an email or a message. One of: `thumb` (Thumbnail (square, 200px)), `medium` (Medium (up to 600px)), `large` (Large (up to 1200px)), `original` (Original (the file as imported)). Default: `medium`.
- A different picture each time (`random_picture`, true/false): Optional. Pick any of the breed's pictures rather than always the first one. Off by default, so a step that runs daily shows the same picture until you turn this on. Default: `false`.
**Outputs**
- `breed_id` (text): The id of the breed in the picture.
- `breed_name` (text): The name of the breed in the picture.
- `byte_size` (number): The file's size in bytes.
- `content_type` (text): The picture's media type, e.g. image/webp.
- `credit` (text): The credit to show wherever the file is used. Its licence requires it.
- `credit_html` (text): The same credit with its links, for HTML.
- `document_ref` (text): The stored document's reference.
- `documents` (list): The stored file, ready to attach or upload. One entry.
- `image` (object): One picture of the breed, in every size the API serves.
- `size` (text): Which size was fetched: thumb, medium, large or original.
- `url` (text): A URL that serves the stored file.
**Example output**
```json
{
"breed_id": "f9643a80-af1d-422a-9f15-18d466822053",
"breed_name": "Caucasian Shepherd Dog",
"byte_size": 51234,
"content_type": "image/webp",
"credit": "Photo by Magdalena Niemiec, CC BY-SA 3.0, via Wikimedia Commons",
"credit_html": "Photo by Magdalena Niemiec, CC BY-SA 3.0, via Wikimedia Commons",
"document_ref": "doc_dog_api_caucasian_shepherd_dog",
"documents": [
{
"content_type": "image/webp",
"document_ref": "doc_dog_api_caucasian_shepherd_dog",
"filename": "caucasian-shepherd-dog-medium-3f1c5f4e.webp",
"size_bytes": 51234,
"url": "/actions/core/serve-document/doc_dog_api_caucasian_shepherd_dog"
}
],
"image": {
"attribution": {
"author": "Magdalena Niemiec",
"license": "CC BY-SA 3.0",
"license_url": "https://creativecommons.org/licenses/by-sa/3.0/",
"source": "wikimedia_commons",
"source_name": "Wikimedia Commons",
"source_url": "https://commons.wikimedia.org/wiki/File:Caucasian_Shepherd_Dog.jpg"
},
"credit": "Photo by Magdalena Niemiec, CC BY-SA 3.0, via Wikimedia Commons",
"credit_html": "Photo by Magdalena Niemiec, CC BY-SA 3.0, via Wikimedia Commons",
"id": "3f1c5f4e-1a6b-4f2e-9b8d-2c0e5a7d4b31",
"large": "https://images.dogapi.dog/caucasian-shepherd-dog-large.webp",
"medium": "https://images.dogapi.dog/caucasian-shepherd-dog-medium.webp",
"thumb": "https://images.dogapi.dog/caucasian-shepherd-dog-thumb.webp",
"url": "https://images.dogapi.dog/caucasian-shepherd-dog.jpg"
},
"size": "medium",
"url": "/actions/core/serve-document/doc_dog_api_caucasian_shepherd_dog"
}
```
### Find a breed
Find the breeds whose name matches some text. This is how a workflow turns what a person typed into the breed the other actions take: "akita inu" comes back as the Akita, with the id the API is keyed by. A name, one of the names a breed also goes by, part of either, or a near miss all find it, and every match says which of those it was. No API key required.
**Inputs**
- Search text (`query`, text, required): The breed to look for. Capitals, accents, word order and a trailing "dog" do not matter, so "Akita", "akita inu" and "akita dog" all find the same breed.
- Number of results (`limit`, number): Optional. How many matches to return in this page. Between 1 and 100; 10 by default. From 1 to 100. Default: `10`.
- Skip (`offset`, number): Optional. How many records to skip before this page. Use the next offset from the previous result to page through. 0 by default. At least 0. Default: `0`.
**Outputs**
- `count` (number): How many records are in this page.
- `has_more` (true/false): True when more records exist than this page holds.
- `matches` (list): The matching breeds in this page, best match first.
- `next_offset` (number): The offset that fetches the next page. Null when this is the last one.
- `query` (text): The text that was searched for.
- `total_count` (number): How many records the whole result holds, across every page. This is the size of the answer, not of the catalogue.
**Example output**
```json
{
"count": 1,
"has_more": false,
"matches": [
{
"coat": {
"colors": [
"gray",
"fawn",
"brindle",
"white"
],
"length": "long",
"text": "long double coat",
"type": "double"
},
"description": "The Caucasian Shepherd dog is a serious guardian breed and should never be taken lightly.",
"female_height": {
"max": 70,
"max_in": 28,
"min": 67,
"min_in": 26,
"text": "67 to 70 cm (26 to 28 in)",
"unit": "cm"
},
"female_weight": {
"max": 70,
"max_lb": 154,
"min": 45,
"min_lb": 99,
"text": "45 to 70 kg (99 to 154 lb)",
"unit": "kg"
},
"group_id": "02124eb6-1baa-410c-90ea-6b8629fb0837",
"group_name": "Working Group",
"has_images": true,
"has_traits": true,
"hypoallergenic": false,
"id": "f9643a80-af1d-422a-9f15-18d466822053",
"image_count": 1,
"images": [
{
"attribution": {
"author": "Magdalena Niemiec",
"license": "CC BY-SA 3.0",
"license_url": "https://creativecommons.org/licenses/by-sa/3.0/",
"source": "wikimedia_commons",
"source_name": "Wikimedia Commons",
"source_url": "https://commons.wikimedia.org/wiki/File:Caucasian_Shepherd_Dog.jpg"
},
"credit": "Photo by Magdalena Niemiec, CC BY-SA 3.0, via Wikimedia Commons",
"credit_html": "Photo by Magdalena Niemiec, CC BY-SA 3.0, via Wikimedia Commons",
"id": "3f1c5f4e-1a6b-4f2e-9b8d-2c0e5a7d4b31",
"large": "https://images.dogapi.dog/caucasian-shepherd-dog-large.webp",
"medium": "https://images.dogapi.dog/caucasian-shepherd-dog-medium.webp",
"thumb": "https://images.dogapi.dog/caucasian-shepherd-dog-thumb.webp",
"url": "https://images.dogapi.dog/caucasian-shepherd-dog.jpg"
}
],
"life": {
"max": 20,
"min": 15,
"text": "15 to 20 years",
"unit": "years"
},
"male_height": {
"max": 75,
"max_in": 30,
"min": 72,
"min_in": 28,
"text": "72 to 75 cm (28 to 30 in)",
"unit": "cm"
},
"male_weight": {
"max": 100,
"max_lb": 220,
"min": 50,
"min_lb": 110,
"text": "50 to 100 kg (110 to 220 lb)",
"unit": "kg"
},
"matched_on": "name",
"name": "Caucasian Shepherd Dog",
"origin": {
"country": "Georgia",
"era": "antiquity",
"region": "Caucasus Mountains",
"text": "Caucasus Mountains, Georgia (antiquity)"
},
"other_names": [
"Caucasian Ovcharka",
"Kavkazskaia Ovtcharka",
"Nagazi"
],
"primary_image": {
"attribution": {
"author": "Magdalena Niemiec",
"license": "CC BY-SA 3.0",
"license_url": "https://creativecommons.org/licenses/by-sa/3.0/",
"source": "wikimedia_commons",
"source_name": "Wikimedia Commons",
"source_url": "https://commons.wikimedia.org/wiki/File:Caucasian_Shepherd_Dog.jpg"
},
"credit": "Photo by Magdalena Niemiec, CC BY-SA 3.0, via Wikimedia Commons",
"credit_html": "Photo by Magdalena Niemiec, CC BY-SA 3.0, via Wikimedia Commons",
"id": "3f1c5f4e-1a6b-4f2e-9b8d-2c0e5a7d4b31",
"large": "https://images.dogapi.dog/caucasian-shepherd-dog-large.webp",
"medium": "https://images.dogapi.dog/caucasian-shepherd-dog-medium.webp",
"thumb": "https://images.dogapi.dog/caucasian-shepherd-dog-thumb.webp",
"url": "https://images.dogapi.dog/caucasian-shepherd-dog.jpg"
},
"recognized_by": [
"AKC",
"FCI",
"UKC"
],
"size": "giant",
"sources": [
{
"title": "Caucasian Shepherd Dog Dog Breed Information - AKC",
"url": "https://www.akc.org/dog-breeds/caucasian-shepherd-dog/"
}
],
"traits": {
"apartment_friendly": 1,
"barking": 4,
"drooling": 3,
"energy": 3,
"exercise_minutes": 60,
"good_with_children": 3,
"good_with_dogs": 2,
"good_with_strangers": 1,
"grooming": 4,
"rated": true,
"shedding": 5,
"temperament": [
"fearless",
"self-confident",
"territorial"
],
"trainability": 2
}
}
],
"next_offset": null,
"query": "caucasian shepherd",
"total_count": 1
}
```
### Find breeds that fit
Find the breeds that suit what a household can actually offer. Say what matters (good with children, quiet, little shedding, an hour of walking at most, an apartment, hypoallergenic) and get the breeds that clear every bar, ranked by how comfortably they clear it, each saying why it is on the list. The ratings are the richest thing the API holds and it has no way to search them, so this is the recommendation they are for. Breeds nobody has rated yet are counted and reported rather than dropped quietly. No API key required.
**Inputs**
- Good with children (`good_with_children`, number): Optional. Keep only breeds rated at least this for being good with children, on the API's scale of 1 (lowest) to 5 (highest). Leave it blank to not ask. From 1 to 5.
- Good with other dogs (`good_with_dogs`, number): Optional. Keep only breeds rated at least this for being good with other dogs, on the API's scale of 1 (lowest) to 5 (highest). Leave it blank to not ask. From 1 to 5.
- Good with strangers (`good_with_strangers`, number): Optional. Keep only breeds rated at least this for being good with strangers, on the API's scale of 1 (lowest) to 5 (highest). Leave it blank to not ask. From 1 to 5.
- Suits an apartment (`apartment_friendly`, number): Optional. Keep only breeds rated at least this for suiting an apartment, on the API's scale of 1 (lowest) to 5 (highest). Leave it blank to not ask. From 1 to 5.
- Trainability (`trainability`, number): Optional. Keep only breeds rated at least this for taking training, on the API's scale of 1 (lowest) to 5 (highest). Leave it blank to not ask. From 1 to 5.
- Energy at most (`max_energy`, number): Optional. Keep only breeds rated no more than this for energy, on the API's scale of 1 (lowest) to 5 (highest). Leave it blank to not ask. From 1 to 5.
- Shedding at most (`max_shedding`, number): Optional. Keep only breeds rated no more than this for shedding, on the API's scale of 1 (lowest) to 5 (highest). Leave it blank to not ask. From 1 to 5.
- Barking at most (`max_barking`, number): Optional. Keep only breeds rated no more than this for barking, on the API's scale of 1 (lowest) to 5 (highest). Leave it blank to not ask. From 1 to 5.
- Grooming at most (`max_grooming`, number): Optional. Keep only breeds rated no more than this for grooming needs, on the API's scale of 1 (lowest) to 5 (highest). Leave it blank to not ask. From 1 to 5.
- Drooling at most (`max_drooling`, number): Optional. Keep only breeds rated no more than this for drooling, on the API's scale of 1 (lowest) to 5 (highest). Leave it blank to not ask. From 1 to 5.
- Daily exercise at most (`max_exercise_minutes`, number): Optional. Keep only breeds that need no more than this many minutes of exercise a day. A breed with no figure recorded is left out when this is set rather than assumed to fit. From 1 to 300.
- Hypoallergenic (`hypoallergenic`, text): Optional. Keep only the breeds that are considered hypoallergenic, or only the ones that are not. Leave it unset to include both. One of: `yes` (Hypoallergenic only), `no` (Exclude hypoallergenic breeds).
- Size (`size`, text): Optional. Keep only breeds of these sizes, worked out from the heavier end of a breed's male weight. Pick any number of them; leave it empty for every size. A breed nobody has weighed is left out when this is set, because there is no weight to judge it by. One or more of: `toy` (Toy (up to 5 kg / 11 lb)), `small` (Small (up to 10 kg / 22 lb)), `medium` (Medium (up to 25 kg / 55 lb)), `large` (Large (up to 45 kg / 99 lb)), `giant` (Giant (over 45 kg / 99 lb)).
- Breed group (`group`, text): Optional. Narrow the answer to one breed group, by name or by the id from an earlier step. The word "Group" is optional, so "Herding" finds the Herding Group. List breed groups shows them all.
- Number of results (`limit`, number): Optional. How many breeds to return in this page. Between 1 and 100; 10 by default. From 1 to 100. Default: `10`.
**Outputs**
- `count` (number): How many records are in this page.
- `group_name` (text): The group the search was narrowed to, or null when it covered every group.
- `has_more` (true/false): True when more breeds fit than were returned.
- `matches` (list): The breeds that fit, best fit first.
- `requirements` (object): The requirements that were actually applied, which is what the fit scores are relative to.
- `skipped_unrated` (number): How many breeds were left out for want of the data a filter needed, so "no breed fits" and "nobody has rated these yet" can be told apart.
- `total_count` (number): How many breeds fit in total.
**Example output**
```json
{
"count": 1,
"group_name": null,
"has_more": false,
"matches": [
{
"coat": {
"colors": [
"gray",
"fawn",
"brindle",
"white"
],
"length": "long",
"text": "long double coat",
"type": "double"
},
"description": "The Caucasian Shepherd dog is a serious guardian breed and should never be taken lightly.",
"female_height": {
"max": 70,
"max_in": 28,
"min": 67,
"min_in": 26,
"text": "67 to 70 cm (26 to 28 in)",
"unit": "cm"
},
"female_weight": {
"max": 70,
"max_lb": 154,
"min": 45,
"min_lb": 99,
"text": "45 to 70 kg (99 to 154 lb)",
"unit": "kg"
},
"fit_score": 50,
"group_id": "02124eb6-1baa-410c-90ea-6b8629fb0837",
"group_name": "Working Group",
"has_images": true,
"has_traits": true,
"hypoallergenic": false,
"id": "f9643a80-af1d-422a-9f15-18d466822053",
"image_count": 1,
"images": [
{
"attribution": {
"author": "Magdalena Niemiec",
"license": "CC BY-SA 3.0",
"license_url": "https://creativecommons.org/licenses/by-sa/3.0/",
"source": "wikimedia_commons",
"source_name": "Wikimedia Commons",
"source_url": "https://commons.wikimedia.org/wiki/File:Caucasian_Shepherd_Dog.jpg"
},
"credit": "Photo by Magdalena Niemiec, CC BY-SA 3.0, via Wikimedia Commons",
"credit_html": "Photo by Magdalena Niemiec, CC BY-SA 3.0, via Wikimedia Commons",
"id": "3f1c5f4e-1a6b-4f2e-9b8d-2c0e5a7d4b31",
"large": "https://images.dogapi.dog/caucasian-shepherd-dog-large.webp",
"medium": "https://images.dogapi.dog/caucasian-shepherd-dog-medium.webp",
"thumb": "https://images.dogapi.dog/caucasian-shepherd-dog-thumb.webp",
"url": "https://images.dogapi.dog/caucasian-shepherd-dog.jpg"
}
],
"life": {
"max": 20,
"min": 15,
"text": "15 to 20 years",
"unit": "years"
},
"male_height": {
"max": 75,
"max_in": 30,
"min": 72,
"min_in": 28,
"text": "72 to 75 cm (28 to 30 in)",
"unit": "cm"
},
"male_weight": {
"max": 100,
"max_lb": 220,
"min": 50,
"min_lb": 110,
"text": "50 to 100 kg (110 to 220 lb)",
"unit": "kg"
},
"name": "Caucasian Shepherd Dog",
"origin": {
"country": "Georgia",
"era": "antiquity",
"region": "Caucasus Mountains",
"text": "Caucasus Mountains, Georgia (antiquity)"
},
"other_names": [
"Caucasian Ovcharka",
"Kavkazskaia Ovtcharka",
"Nagazi"
],
"primary_image": {
"attribution": {
"author": "Magdalena Niemiec",
"license": "CC BY-SA 3.0",
"license_url": "https://creativecommons.org/licenses/by-sa/3.0/",
"source": "wikimedia_commons",
"source_name": "Wikimedia Commons",
"source_url": "https://commons.wikimedia.org/wiki/File:Caucasian_Shepherd_Dog.jpg"
},
"credit": "Photo by Magdalena Niemiec, CC BY-SA 3.0, via Wikimedia Commons",
"credit_html": "Photo by Magdalena Niemiec, CC BY-SA 3.0, via Wikimedia Commons",
"id": "3f1c5f4e-1a6b-4f2e-9b8d-2c0e5a7d4b31",
"large": "https://images.dogapi.dog/caucasian-shepherd-dog-large.webp",
"medium": "https://images.dogapi.dog/caucasian-shepherd-dog-medium.webp",
"thumb": "https://images.dogapi.dog/caucasian-shepherd-dog-thumb.webp",
"url": "https://images.dogapi.dog/caucasian-shepherd-dog.jpg"
},
"recognized_by": [
"AKC",
"FCI",
"UKC"
],
"size": "giant",
"sources": [
{
"title": "Caucasian Shepherd Dog Dog Breed Information - AKC",
"url": "https://www.akc.org/dog-breeds/caucasian-shepherd-dog/"
}
],
"traits": {
"apartment_friendly": 1,
"barking": 4,
"drooling": 3,
"energy": 3,
"exercise_minutes": 60,
"good_with_children": 3,
"good_with_dogs": 2,
"good_with_strangers": 1,
"grooming": 4,
"rated": true,
"shedding": 5,
"temperament": [
"fearless",
"self-confident",
"territorial"
],
"trainability": 2
},
"why": [
"Good with children: 3 (asked for 2 or more)",
"Barking: 4 (asked for 4 or less)"
]
}
],
"requirements": {
"good_with_children": 2,
"max_barking": 4
},
"skipped_unrated": 308,
"total_count": 1
}
```
### Get a breed
Get one breed in full: what it weighs and how tall it stands in both kilograms and pounds, how long it lives, where it came from, what its coat is like, how it behaves on ten rated scales, the clubs that recognise it, and any pictures with the credit each one's licence requires. Name it however you have it, a name or an id. No API key required.
**Inputs**
- Breed (`breed`, text, required): The breed, named however you have it: its name, one of the names it also goes by, or the id from an earlier step. Capitals, accents and a trailing "dog" do not matter, so "german shepherd" finds the German Shepherd Dog. A word that fits several breeds is rejected rather than guessed, and Find a breed will pick one.
**Outputs**: One breed, with everything the API records about it.
- `coat` (object): What the breed's coat is like.
- `description` (text): A sentence or two about the breed.
- `female_height` (object): A female's height at the withers.
- `female_weight` (object): A female's weight.
- `group_id` (text): The id of the group it belongs to.
- `group_name` (text): The group's name, e.g. "Herding Group". The API answers with the id alone; the name is filled in here.
- `has_images` (true/false): True when there is a picture to show. Branch on it rather than on the pictures list being empty.
- `has_traits` (true/false): True when the breed has the ten behaviour ratings. Most breeds do not yet, so check this before reading one.
- `hypoallergenic` (true/false): Whether the breed is considered hypoallergenic.
- `id` (text): The breed's id, which is what the API is keyed by. Pass it straight to another step that takes a breed.
- `image_count` (number): How many pictures of the breed there are.
- `images` (list): Every picture of the breed. Empty for most breeds, which have none imported yet.
- `life` (object): Life expectancy in years.
- `male_height` (object): A male's height at the withers.
- `male_weight` (object): A male's weight.
- `name` (text): The breed's name, e.g. "Caucasian Shepherd Dog".
- `origin` (object): Where the breed comes from.
- `other_names` (list): Names the breed also goes by, e.g. ["Akita Inu"]. Any of them can be passed back in as the breed.
- `primary_image` (object): One picture of the breed, in every size the API serves.
- `recognized_by` (list): The kennel clubs that recognise it, e.g. ["AKC","FCI"].
- `size` (text): How big the breed is, worked out from the heavier end of its male weight: toy (up to 5kg), small (10kg), medium (25kg), large (45kg) or giant. Null for a breed nobody has weighed.
- `sources` (list): The pages the researched attributes were taken from.
- `traits` (object): How the breed behaves, each rating from 1 (lowest) to 5 (highest) relative to dogs in general. These are researched estimates, not measurements, and they are filled in as a block: a breed either has all ten or none.
**Example output**
```json
{
"coat": {
"colors": [
"gray",
"fawn",
"brindle",
"white"
],
"length": "long",
"text": "long double coat",
"type": "double"
},
"description": "The Caucasian Shepherd dog is a serious guardian breed and should never be taken lightly.",
"female_height": {
"max": 70,
"max_in": 28,
"min": 67,
"min_in": 26,
"text": "67 to 70 cm (26 to 28 in)",
"unit": "cm"
},
"female_weight": {
"max": 70,
"max_lb": 154,
"min": 45,
"min_lb": 99,
"text": "45 to 70 kg (99 to 154 lb)",
"unit": "kg"
},
"group_id": "02124eb6-1baa-410c-90ea-6b8629fb0837",
"group_name": "Working Group",
"has_images": true,
"has_traits": true,
"hypoallergenic": false,
"id": "f9643a80-af1d-422a-9f15-18d466822053",
"image_count": 1,
"images": [
{
"attribution": {
"author": "Magdalena Niemiec",
"license": "CC BY-SA 3.0",
"license_url": "https://creativecommons.org/licenses/by-sa/3.0/",
"source": "wikimedia_commons",
"source_name": "Wikimedia Commons",
"source_url": "https://commons.wikimedia.org/wiki/File:Caucasian_Shepherd_Dog.jpg"
},
"credit": "Photo by Magdalena Niemiec, CC BY-SA 3.0, via Wikimedia Commons",
"credit_html": "Photo by Magdalena Niemiec, CC BY-SA 3.0, via Wikimedia Commons",
"id": "3f1c5f4e-1a6b-4f2e-9b8d-2c0e5a7d4b31",
"large": "https://images.dogapi.dog/caucasian-shepherd-dog-large.webp",
"medium": "https://images.dogapi.dog/caucasian-shepherd-dog-medium.webp",
"thumb": "https://images.dogapi.dog/caucasian-shepherd-dog-thumb.webp",
"url": "https://images.dogapi.dog/caucasian-shepherd-dog.jpg"
}
],
"life": {
"max": 20,
"min": 15,
"text": "15 to 20 years",
"unit": "years"
},
"male_height": {
"max": 75,
"max_in": 30,
"min": 72,
"min_in": 28,
"text": "72 to 75 cm (28 to 30 in)",
"unit": "cm"
},
"male_weight": {
"max": 100,
"max_lb": 220,
"min": 50,
"min_lb": 110,
"text": "50 to 100 kg (110 to 220 lb)",
"unit": "kg"
},
"name": "Caucasian Shepherd Dog",
"origin": {
"country": "Georgia",
"era": "antiquity",
"region": "Caucasus Mountains",
"text": "Caucasus Mountains, Georgia (antiquity)"
},
"other_names": [
"Caucasian Ovcharka",
"Kavkazskaia Ovtcharka",
"Nagazi"
],
"primary_image": {
"attribution": {
"author": "Magdalena Niemiec",
"license": "CC BY-SA 3.0",
"license_url": "https://creativecommons.org/licenses/by-sa/3.0/",
"source": "wikimedia_commons",
"source_name": "Wikimedia Commons",
"source_url": "https://commons.wikimedia.org/wiki/File:Caucasian_Shepherd_Dog.jpg"
},
"credit": "Photo by Magdalena Niemiec, CC BY-SA 3.0, via Wikimedia Commons",
"credit_html": "Photo by Magdalena Niemiec, CC BY-SA 3.0, via Wikimedia Commons",
"id": "3f1c5f4e-1a6b-4f2e-9b8d-2c0e5a7d4b31",
"large": "https://images.dogapi.dog/caucasian-shepherd-dog-large.webp",
"medium": "https://images.dogapi.dog/caucasian-shepherd-dog-medium.webp",
"thumb": "https://images.dogapi.dog/caucasian-shepherd-dog-thumb.webp",
"url": "https://images.dogapi.dog/caucasian-shepherd-dog.jpg"
},
"recognized_by": [
"AKC",
"FCI",
"UKC"
],
"size": "giant",
"sources": [
{
"title": "Caucasian Shepherd Dog Dog Breed Information - AKC",
"url": "https://www.akc.org/dog-breeds/caucasian-shepherd-dog/"
}
],
"traits": {
"apartment_friendly": 1,
"barking": 4,
"drooling": 3,
"energy": 3,
"exercise_minutes": 60,
"good_with_children": 3,
"good_with_dogs": 2,
"good_with_strangers": 1,
"grooming": 4,
"rated": true,
"shedding": 5,
"temperament": [
"fearless",
"self-confident",
"territorial"
],
"trainability": 2
}
}
```
### Get a breed group
Get one breed group and every breed in it, by name or by id. "Herding" finds the Herding Group: the word the API appends is optional. Each breed comes back as an id and a name, which is what Get a breed takes for the rest of it. No API key required.
**Inputs**
- Breed group (`group`, text, required): The breed group, by name or by the id from an earlier step. The word "Group" is optional, so "Herding" finds the Herding Group. List breed groups shows them all.
**Outputs**: One breed group and the breeds in it.
- `breed_count` (number): How many breeds belong to the group.
- `breeds` (list): The breeds in the group, by id and name.
- `id` (text): The group's id.
- `name` (text): The group's name, e.g. "Herding Group".
**Example output**
```json
{
"breed_count": 1,
"breeds": [
{
"has_images": true,
"id": "f9643a80-af1d-422a-9f15-18d466822053",
"name": "Caucasian Shepherd Dog"
}
],
"id": "02124eb6-1baa-410c-90ea-6b8629fb0837",
"name": "Working Group"
}
```
### Get a dog picture
Get a picture of a breed, or of a random breed, at whichever size the message needs, with the credit its licence requires already written out in text and in HTML. The pictures come from Wikimedia Commons under their authors' licences, which means the credit has to be shown wherever the picture is, so it comes back with it. Most breeds have no picture yet, and a breed without one says so rather than failing silently. No API key required.
**Inputs**
- Breed (`breed`, text): Optional. The breed to show, named however you have it: its name, one of the names it also goes by, or the id from an earlier step. Leave it blank for a picture of a random breed.
- Picture size (`picture_size`, text): Optional. Which size to fetch. Medium by default, which is the one to put in an email or a message. One of: `thumb` (Thumbnail (square, 200px)), `medium` (Medium (up to 600px)), `large` (Large (up to 1200px)), `original` (Original (the file as imported)). Default: `medium`.
- A different picture each time (`random_picture`, true/false): Optional. Pick any of the breed's pictures rather than always the first one. Off by default, so a step that runs daily shows the same picture until you turn this on. Default: `false`.
**Outputs**
- `alt_text` (text): A description for a screen reader, e.g. "Akita dog". Use it as the alt text wherever the picture is shown.
- `breed_id` (text): The id of the breed in the picture.
- `breed_name` (text): The name of the breed in the picture.
- `credit` (text): The credit to show beside the picture. Its licence requires it.
- `credit_html` (text): The same credit with the licence and source page linked, for an HTML email or a web page.
- `group_name` (text): The group that breed belongs to.
- `image` (object): One picture of the breed, in every size the API serves.
- `image_count` (number): How many pictures of the breed there are to choose from.
- `size` (text): Which size the URL is: thumb, medium, large or original.
- `url` (text): The picture at the size that was asked for. Served openly, so it can go straight into an image tag or a message; Download a dog picture is for the steps that need the file.
**Example output**
```json
{
"alt_text": "Caucasian Shepherd Dog dog",
"breed_id": "f9643a80-af1d-422a-9f15-18d466822053",
"breed_name": "Caucasian Shepherd Dog",
"credit": "Photo by Magdalena Niemiec, CC BY-SA 3.0, via Wikimedia Commons",
"credit_html": "Photo by Magdalena Niemiec, CC BY-SA 3.0, via Wikimedia Commons",
"group_name": "Working Group",
"image": {
"attribution": {
"author": "Magdalena Niemiec",
"license": "CC BY-SA 3.0",
"license_url": "https://creativecommons.org/licenses/by-sa/3.0/",
"source": "wikimedia_commons",
"source_name": "Wikimedia Commons",
"source_url": "https://commons.wikimedia.org/wiki/File:Caucasian_Shepherd_Dog.jpg"
},
"credit": "Photo by Magdalena Niemiec, CC BY-SA 3.0, via Wikimedia Commons",
"credit_html": "Photo by Magdalena Niemiec, CC BY-SA 3.0, via Wikimedia Commons",
"id": "3f1c5f4e-1a6b-4f2e-9b8d-2c0e5a7d4b31",
"large": "https://images.dogapi.dog/caucasian-shepherd-dog-large.webp",
"medium": "https://images.dogapi.dog/caucasian-shepherd-dog-medium.webp",
"thumb": "https://images.dogapi.dog/caucasian-shepherd-dog-thumb.webp",
"url": "https://images.dogapi.dog/caucasian-shepherd-dog.jpg"
},
"image_count": 1,
"size": "medium",
"url": "https://images.dogapi.dog/caucasian-shepherd-dog-medium.webp"
}
```
### Get dog facts
Get one to five random dog facts, each a sentence ready to put straight into a message. The service picks different ones every time and marks the answer uncacheable, so a step that runs daily says something new each day. No API key required.
**Inputs**
- How many (`limit`, number): Optional. How many facts to return. Between 1 and 5; 1 by default. The service caps it at five itself, and says nothing about having done so, so anything higher comes back as five. From 1 to 5. Default: `1`.
**Outputs**
- `count` (number): How many facts came back.
- `fact` (text): The first fact's text on its own, for the common case of wanting one sentence.
- `facts` (list): The facts, each with its id.
- `requested_count` (number): How many were asked for after the service's own cap of five was applied.
**Example output**
```json
{
"count": 1,
"fact": "Many foot disorders in dogs are caused by long toenails.",
"facts": [
{
"body": "Many foot disorders in dogs are caused by long toenails.",
"id": "1cd1a16d-6fe1-40ea-9dd2-c21dd0f7c24e"
}
],
"requested_count": 1
}
```
### List breed groups
List the breed groups, around twenty of them, each with the breeds that belong to it. The API names a group's breeds by id alone, so the names come back filled in here. Use it to offer a person the groups to pick from, or to walk a report through the catalogue a group at a time. No API key required.
**Inputs**
- Number of results (`limit`, number): Optional. How many groups to return in this page. Between 1 and 100; 25 by default. From 1 to 100. Default: `25`.
- Skip (`offset`, number): Optional. How many records to skip before this page. Use the next offset from the previous result to page through. 0 by default. At least 0. Default: `0`.
**Outputs**
- `breed_count` (number): How many breeds the groups cover between them.
- `count` (number): How many records are in this page.
- `groups` (list): The breed groups in this page.
- `has_more` (true/false): True when more records exist than this page holds.
- `next_offset` (number): The offset that fetches the next page. Null when this is the last one.
- `total_count` (number): How many records the whole result holds, across every page. This is the size of the answer, not of the catalogue.
**Example output**
```json
{
"breed_count": 340,
"count": 1,
"groups": [
{
"breed_count": 1,
"breeds": [
{
"has_images": true,
"id": "f9643a80-af1d-422a-9f15-18d466822053",
"name": "Caucasian Shepherd Dog"
}
],
"id": "02124eb6-1baa-410c-90ea-6b8629fb0837",
"name": "Working Group"
}
],
"has_more": false,
"next_offset": null,
"total_count": 20
}
```
### List breeds
Browse the API's 340-odd breeds, a page at a time, narrowed to the ones worth looking at: one breed group, one country, one coat, one kennel club, the hypoallergenic ones, the sizes you want, or only the breeds that have a picture. Order them by name, by weight or by how long they live. No API key required.
**Inputs**
- Breed group (`group`, text): Optional. Narrow the answer to one breed group, by name or by the id from an earlier step. The word "Group" is optional, so "Herding" finds the Herding Group. List breed groups shows them all.
- Only breeds with pictures (`only_with_pictures`, true/false): Optional. Keep only the breeds that have a picture. Most have none imported yet, so turn this on when the result is going on a screen. Off by default, which leaves the listing alone. Default: `false`.
- Hypoallergenic (`hypoallergenic`, text): Optional. Keep only the breeds that are considered hypoallergenic, or only the ones that are not. Leave it unset to include both. One of: `yes` (Hypoallergenic only), `no` (Exclude hypoallergenic breeds).
- Size (`size`, text): Optional. Keep only breeds of these sizes, worked out from the heavier end of a breed's male weight. Pick any number of them; leave it empty for every size. A breed nobody has weighed is left out when this is set, because there is no weight to judge it by. One or more of: `toy` (Toy (up to 5 kg / 11 lb)), `small` (Small (up to 10 kg / 22 lb)), `medium` (Medium (up to 25 kg / 55 lb)), `large` (Large (up to 45 kg / 99 lb)), `giant` (Giant (over 45 kg / 99 lb)).
- Coat type (`coat_type`, text): Optional. Keep only breeds with this kind of coat. Leave it unset for any. One of: `smooth`, `short`, `medium`, `long`, `wire`, `curly`, `double`, `hairless`, `corded`.
- Coat length (`coat_length`, text): Optional. Keep only breeds whose coat is this long. Leave it unset for any. One of: `hairless`, `short`, `medium`, `long`.
- Country of origin (`origin_country`, text): Optional. Keep only breeds from this country, as the API spells it. Capitals and accents do not matter.
- Recognised by (`recognized_by`, text): Optional. Keep only breeds this kennel club recognises. Leave it unset for all of them. One of: `AKC` (AKC (American Kennel Club)), `FCI` (FCI (Federation Cynologique Internationale)), `UKC` (UKC (United Kennel Club)), `KC` (KC (The Kennel Club, UK)), `CKC` (CKC (Canadian Kennel Club)), `ANKC` (ANKC (Australian National Kennel Council)), `NZKC` (NZKC (New Zealand Kennel Club)).
- Order by (`sort`, text): Optional. How to order the result. By name by default, which is the order the API itself uses. A breed with no weight or lifespan recorded goes to the end rather than to the front. One of: `name` (Name, A to Z), `heaviest` (Heaviest first), `lightest` (Lightest first), `longest_living` (Longest living first). Default: `name`.
- Number of results (`limit`, number): Optional. How many breeds to return in this page. Between 1 and 100; 25 by default. From 1 to 100. Default: `25`.
- Skip (`offset`, number): Optional. How many records to skip before this page. Use the next offset from the previous result to page through. 0 by default. At least 0. Default: `0`.
**Outputs**
- `breeds` (list): The breeds in this page.
- `catalogue_count` (number): How many breeds the API holds in total, so a filtered total can be read against it.
- `count` (number): How many records are in this page.
- `group_name` (text): The group the listing was narrowed to, or null when it covered every group.
- `has_more` (true/false): True when more records exist than this page holds.
- `next_offset` (number): The offset that fetches the next page. Null when this is the last one.
- `sort` (text): The order the breeds came back in.
- `total_count` (number): How many records the whole result holds, across every page. This is the size of the answer, not of the catalogue.
**Example output**
```json
{
"breeds": [
{
"coat": {
"colors": [
"gray",
"fawn",
"brindle",
"white"
],
"length": "long",
"text": "long double coat",
"type": "double"
},
"description": "The Caucasian Shepherd dog is a serious guardian breed and should never be taken lightly.",
"female_height": {
"max": 70,
"max_in": 28,
"min": 67,
"min_in": 26,
"text": "67 to 70 cm (26 to 28 in)",
"unit": "cm"
},
"female_weight": {
"max": 70,
"max_lb": 154,
"min": 45,
"min_lb": 99,
"text": "45 to 70 kg (99 to 154 lb)",
"unit": "kg"
},
"group_id": "02124eb6-1baa-410c-90ea-6b8629fb0837",
"group_name": "Working Group",
"has_images": true,
"has_traits": true,
"hypoallergenic": false,
"id": "f9643a80-af1d-422a-9f15-18d466822053",
"image_count": 1,
"images": [
{
"attribution": {
"author": "Magdalena Niemiec",
"license": "CC BY-SA 3.0",
"license_url": "https://creativecommons.org/licenses/by-sa/3.0/",
"source": "wikimedia_commons",
"source_name": "Wikimedia Commons",
"source_url": "https://commons.wikimedia.org/wiki/File:Caucasian_Shepherd_Dog.jpg"
},
"credit": "Photo by Magdalena Niemiec, CC BY-SA 3.0, via Wikimedia Commons",
"credit_html": "Photo by Magdalena Niemiec, CC BY-SA 3.0, via Wikimedia Commons",
"id": "3f1c5f4e-1a6b-4f2e-9b8d-2c0e5a7d4b31",
"large": "https://images.dogapi.dog/caucasian-shepherd-dog-large.webp",
"medium": "https://images.dogapi.dog/caucasian-shepherd-dog-medium.webp",
"thumb": "https://images.dogapi.dog/caucasian-shepherd-dog-thumb.webp",
"url": "https://images.dogapi.dog/caucasian-shepherd-dog.jpg"
}
],
"life": {
"max": 20,
"min": 15,
"text": "15 to 20 years",
"unit": "years"
},
"male_height": {
"max": 75,
"max_in": 30,
"min": 72,
"min_in": 28,
"text": "72 to 75 cm (28 to 30 in)",
"unit": "cm"
},
"male_weight": {
"max": 100,
"max_lb": 220,
"min": 50,
"min_lb": 110,
"text": "50 to 100 kg (110 to 220 lb)",
"unit": "kg"
},
"name": "Caucasian Shepherd Dog",
"origin": {
"country": "Georgia",
"era": "antiquity",
"region": "Caucasus Mountains",
"text": "Caucasus Mountains, Georgia (antiquity)"
},
"other_names": [
"Caucasian Ovcharka",
"Kavkazskaia Ovtcharka",
"Nagazi"
],
"primary_image": {
"attribution": {
"author": "Magdalena Niemiec",
"license": "CC BY-SA 3.0",
"license_url": "https://creativecommons.org/licenses/by-sa/3.0/",
"source": "wikimedia_commons",
"source_name": "Wikimedia Commons",
"source_url": "https://commons.wikimedia.org/wiki/File:Caucasian_Shepherd_Dog.jpg"
},
"credit": "Photo by Magdalena Niemiec, CC BY-SA 3.0, via Wikimedia Commons",
"credit_html": "Photo by Magdalena Niemiec, CC BY-SA 3.0, via Wikimedia Commons",
"id": "3f1c5f4e-1a6b-4f2e-9b8d-2c0e5a7d4b31",
"large": "https://images.dogapi.dog/caucasian-shepherd-dog-large.webp",
"medium": "https://images.dogapi.dog/caucasian-shepherd-dog-medium.webp",
"thumb": "https://images.dogapi.dog/caucasian-shepherd-dog-thumb.webp",
"url": "https://images.dogapi.dog/caucasian-shepherd-dog.jpg"
},
"recognized_by": [
"AKC",
"FCI",
"UKC"
],
"size": "giant",
"sources": [
{
"title": "Caucasian Shepherd Dog Dog Breed Information - AKC",
"url": "https://www.akc.org/dog-breeds/caucasian-shepherd-dog/"
}
],
"traits": {
"apartment_friendly": 1,
"barking": 4,
"drooling": 3,
"energy": 3,
"exercise_minutes": 60,
"good_with_children": 3,
"good_with_dogs": 2,
"good_with_strangers": 1,
"grooming": 4,
"rated": true,
"shedding": 5,
"temperament": [
"fearless",
"self-confident",
"territorial"
],
"trainability": 2
}
}
],
"catalogue_count": 340,
"count": 1,
"group_name": "Working Group",
"has_more": true,
"next_offset": 25,
"sort": "name",
"total_count": 32
}
```