# RandomDog

> Pull dogs into a workflow from RandomDog, an open collection of about a thousand dog photos, animations and videos that anyone can read: one at random for a daily picture, a handful at once for a gallery, or the whole collection a page at a time. Every dog comes back with alt text and with what kind of file it is, so a step can tell a photograph from a video before putting it in an email, and still photographs are what is drawn unless you ask for more. Count what the collection holds by format, or download a dog to post or attach. No account or API key required.

App · Images & Design · 5 actions. Web page: https://docs.lodol.com/docs/integrations/random-dog

## Actions

### Download a dog

Download a dog as a file, so a later step can attach it to an email, post it to a chat or put it in storage. Pass a URL from an earlier step to fetch that exact dog, or leave it blank to draw one at random. Only RandomDog's own address is accepted, and a file too large to be worth pulling down is refused with its size rather than downloaded. No API key required.

**Inputs**

- Dog URL (`url`, text): Optional. The exact dog to download, as returned by one of the other actions. Leave blank to draw one at random. Only RandomDog's own address is accepted.
- What to draw (`media`, text): Optional. Which kinds of file to draw from when no URL is given. RandomDog's collection holds videos and animated GIFs as well as photographs, and a video URL cannot be shown in an image tag or an email, so still photographs are the default. Pick Anything at all for the whole collection, videos included. One of: `photos` (Still photographs), `photos_and_animations` (Photographs and animated GIFs), `animations` (Animated GIFs only), `videos` (Videos only), `anything` (Anything at all). Default: `photos`.
- Only these extensions (`extensions`, text): Optional. Limit the draw to exact file extensions, comma-separated, e.g. png or jpg, png. Capitals and a leading dot are both fine: the collection holds .jpg and .JPG alike and they are treated as one extension. Setting this replaces What to draw.

**Outputs**

- `byte_size` (number): The file's size in bytes.
- `content_type` (text): The file's media type, e.g. image/jpeg or video/mp4.
- `document_ref` (text): The stored document's reference.
- `documents` (list): The downloaded file as a document, ready to attach to a later step.
- `dog` (object): One dog, ready to embed or to feed another step.
- `source_url` (text): The RandomDog address the file was downloaded from, as opposed to the stored document's own URL.
- `url` (text): A URL that serves the stored file.

**Example output**

```json
{
  "byte_size": 33577,
  "content_type": "image/jpeg",
  "document_ref": "doc_random_dog_4288af3e",
  "documents": [
    {
      "content_type": "image/jpeg",
      "document_ref": "doc_random_dog_4288af3e",
      "filename": "random-dog-4288af3e-a40e-495c-bd4a-1af06bee9c8c.jpg",
      "size_bytes": 33577,
      "url": "/actions/core/serve-document/doc_random_dog_4288af3e"
    }
  ],
  "dog": {
    "alt_text": "A photo of a random dog",
    "content_type": "image/jpeg",
    "extension": "jpg",
    "filename": "4288af3e-a40e-495c-bd4a-1af06bee9c8c.jpg",
    "id": "4288af3e-a40e-495c-bd4a-1af06bee9c8c",
    "is_video": false,
    "media_kind": "photo",
    "size_bytes": 33577,
    "url": "https://random.dog/4288af3e-a40e-495c-bd4a-1af06bee9c8c.jpg"
  },
  "source_url": "https://random.dog/4288af3e-a40e-495c-bd4a-1af06bee9c8c.jpg",
  "url": "/actions/core/serve-document/doc_random_dog_4288af3e"
}
```

### Get a random dog

Get one dog at random from RandomDog's collection of about a thousand, with a URL that can be embedded straight into a message or an email and alt text ready to caption it. Still photographs by default, because the collection holds videos and animated GIFs too and a video cannot be shown as a picture; ask for those explicitly when you want them. No API key required.

**Inputs**

- What to draw (`media`, text): Optional. Which kinds of file to draw from. RandomDog's collection holds videos and animated GIFs as well as photographs, and a video URL cannot be shown in an image tag or an email, so still photographs are the default. Pick Anything at all for the whole collection, videos included. One of: `photos` (Still photographs), `photos_and_animations` (Photographs and animated GIFs), `animations` (Animated GIFs only), `videos` (Videos only), `anything` (Anything at all). Default: `photos`.
- Only these extensions (`extensions`, text): Optional. Limit the draw to exact file extensions, comma-separated, e.g. png or jpg, png. Capitals and a leading dot are both fine: the collection holds .jpg and .JPG alike and they are treated as one extension. Setting this replaces What to draw.

**Outputs**

- `alt_text` (text): A description of the file for a screen reader, e.g. A photo of a random dog. Use it as the alt text wherever the dog is shown.
- `content_type` (text): The file's media type, e.g. image/jpeg or video/mp4.
- `dog` (object): One dog, ready to embed or to feed another step.
- `extension` (text): The file's extension, lowercased and without the dot, e.g. jpg. The collection holds both jpg and JPG, so this is always lowercase. Null for the rare file that has no extension.
- `extensions` (list): The exact extensions this step was limited to, lowercased and without dots. Empty when the kind of file was chosen instead.
- `filename` (text): The file's name as the collection lists it, e.g. 4288af3e-a40e-495c-bd4a-1af06bee9c8c.jpg. This is the only thing that tells one dog from another.
- `id` (text): The file's name without its extension. Most are random identifiers, but not all of them, so treat it as a label rather than a UUID.
- `is_video` (true/false): True when the file is a video, which is the case an image tag or an email cannot show. False for photographs and animated GIFs, both of which render as pictures.
- `media` (text): Which kinds of file this step asked for, echoed back so a result explains itself: photos, photos_and_animations, animations, videos or anything.
- `media_kind` (text): What this file is: photo for a still photograph, animation for an animated GIF, video for an MP4 or WebM, or other for a format this integration has not seen. Branch on it before treating the URL as a picture.
- `size_bytes` (number): The file's size in bytes. RandomDog reports this only for a single random pick and for a download, so it is null on the rows of a listing or a batch.
- `url` (text): The file itself. RandomDog serves these openly with CORS allowed, so the URL can be embedded directly in an email or a message; Download a dog is for steps that need the file.

**Example output**

```json
{
  "alt_text": "A photo of a random dog",
  "content_type": "image/jpeg",
  "dog": {
    "alt_text": "A photo of a random dog",
    "content_type": "image/jpeg",
    "extension": "jpg",
    "filename": "4288af3e-a40e-495c-bd4a-1af06bee9c8c.jpg",
    "id": "4288af3e-a40e-495c-bd4a-1af06bee9c8c",
    "is_video": false,
    "media_kind": "photo",
    "size_bytes": 33577,
    "url": "https://random.dog/4288af3e-a40e-495c-bd4a-1af06bee9c8c.jpg"
  },
  "extension": "jpg",
  "extensions": [],
  "filename": "4288af3e-a40e-495c-bd4a-1af06bee9c8c.jpg",
  "id": "4288af3e-a40e-495c-bd4a-1af06bee9c8c",
  "is_video": false,
  "media": "photos",
  "media_kind": "photo",
  "size_bytes": 33577,
  "url": "https://random.dog/4288af3e-a40e-495c-bd4a-1af06bee9c8c.jpg"
}
```

### Get several random dogs

Get a handful of dogs at random in one step, for a gallery, a digest or a row of pictures. No two are the same unless repeats are allowed, and the whole batch costs one request however many are asked for. Asking for more than the collection holds returns all of them rather than failing. No API key required.

**Inputs**

- How many (`count`, number): Optional. How many dogs to draw. Between 1 and 50; one by default. From 1 to 50. Default: `1`.
- What to draw (`media`, text): Optional. Which kinds of file to draw from. RandomDog's collection holds videos and animated GIFs as well as photographs, and a video URL cannot be shown in an image tag or an email, so still photographs are the default. Pick Anything at all for the whole collection, videos included. One of: `photos` (Still photographs), `photos_and_animations` (Photographs and animated GIFs), `animations` (Animated GIFs only), `videos` (Videos only), `anything` (Anything at all). Default: `photos`.
- Only these extensions (`extensions`, text): Optional. Limit the draw to exact file extensions, comma-separated, e.g. png or jpg, png. Capitals and a leading dot are both fine: the collection holds .jpg and .JPG alike and they are treated as one extension. Setting this replaces What to draw.
- Allow repeats (`allow_repeats`, true/false): Optional. Let the same dog be drawn more than once. Off by default, so a batch is a set of different dogs. Default: `false`.

**Outputs**

- `allow_repeats` (true/false): Whether the same dog could be drawn twice.
- `catalogue_count` (number): How many dogs there are in the whole collection, before any filter. Compare it with the match to see what a filter left out.
- `count` (number): How many dogs are in this result.
- `dog` (object): The first dog, so a step that wanted one does not have to index into the list.
- `dogs` (list): The dogs that were drawn.
- `extensions` (list): The exact extensions this step was limited to, lowercased and without dots. Empty when the kind of file was chosen instead.
- `matching_count` (number): How many dogs in the collection the batch was drawn from.
- `media` (text): Which kinds of file this step asked for, echoed back so a result explains itself: photos, photos_and_animations, animations, videos or anything.
- `requested_count` (number): How many dogs were asked for. Higher than count when the match ran out.

**Example output**

```json
{
  "allow_repeats": false,
  "catalogue_count": 1030,
  "count": 1,
  "dog": {
    "alt_text": "A photo of a random dog",
    "content_type": "image/jpeg",
    "extension": "jpg",
    "filename": "4288af3e-a40e-495c-bd4a-1af06bee9c8c.jpg",
    "id": "4288af3e-a40e-495c-bd4a-1af06bee9c8c",
    "is_video": false,
    "media_kind": "photo",
    "size_bytes": null,
    "url": "https://random.dog/4288af3e-a40e-495c-bd4a-1af06bee9c8c.jpg"
  },
  "dogs": [
    {
      "alt_text": "A photo of a random dog",
      "content_type": "image/jpeg",
      "extension": "jpg",
      "filename": "4288af3e-a40e-495c-bd4a-1af06bee9c8c.jpg",
      "id": "4288af3e-a40e-495c-bd4a-1af06bee9c8c",
      "is_video": false,
      "media_kind": "photo",
      "size_bytes": null,
      "url": "https://random.dog/4288af3e-a40e-495c-bd4a-1af06bee9c8c.jpg"
    }
  ],
  "extensions": [],
  "matching_count": 902,
  "media": "photos",
  "requested_count": 1
}
```

### List the dogs

List every dog in RandomDog's collection, a page at a time, to build a gallery or to work through the whole thing. Each row carries the file's URL and what kind of file it is. The result says both how many dogs matched and how many there are altogether, and a filter that matches nothing is an empty page rather than an error, so a workflow can branch on the count. No API key required.

**Inputs**

- What to draw (`media`, text): Optional. Which kinds of file to list. RandomDog's collection holds videos and animated GIFs as well as photographs, and a video URL cannot be shown in an image tag or an email, so still photographs are the default. Pick Anything at all for the whole collection, videos included. One of: `photos` (Still photographs), `photos_and_animations` (Photographs and animated GIFs), `animations` (Animated GIFs only), `videos` (Videos only), `anything` (Anything at all). Default: `photos`.
- Only these extensions (`extensions`, text): Optional. Limit the draw to exact file extensions, comma-separated, e.g. png or jpg, png. Capitals and a leading dot are both fine: the collection holds .jpg and .JPG alike and they are treated as one extension. Setting this replaces What to draw.
- Number of results (`limit`, number): Optional. How many dogs to return in this page. Between 1 and 100; 25 by default. From 1 to 100. Default: `25`.
- Skip (`offset`, number): Optional. How many dogs 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**

- `catalogue_count` (number): How many dogs there are in the whole collection, before any filter. Compare it with the match to see what a filter left out.
- `count` (number): How many dogs are in this result.
- `dogs` (list): The dogs in this page.
- `extensions` (list): The exact extensions this step was limited to, lowercased and without dots. Empty when the kind of file was chosen instead.
- `has_more` (true/false): True when more dogs matched than this page holds.
- `media` (text): Which kinds of file this step asked for, echoed back so a result explains itself: photos, photos_and_animations, animations, videos or anything.
- `next_offset` (number): The offset that fetches the next page. Null when this is the last one.
- `total_count` (number): How many dogs matched, across every page. This is what the paging runs to.

**Example output**

```json
{
  "catalogue_count": 1030,
  "count": 1,
  "dogs": [
    {
      "alt_text": "A photo of a random dog",
      "content_type": "image/jpeg",
      "extension": "jpg",
      "filename": "4288af3e-a40e-495c-bd4a-1af06bee9c8c.jpg",
      "id": "4288af3e-a40e-495c-bd4a-1af06bee9c8c",
      "is_video": false,
      "media_kind": "photo",
      "size_bytes": null,
      "url": "https://random.dog/4288af3e-a40e-495c-bd4a-1af06bee9c8c.jpg"
    }
  ],
  "extensions": [],
  "has_more": true,
  "media": "photos",
  "next_offset": 25,
  "total_count": 902
}
```

### Summarize the collection

Count what RandomDog holds, by kind of file and by extension: how many photographs, how many animated GIFs, how many videos, and what share of the collection each format is. Read it to report on the collection, or to check there is enough of a format worth drawing from before a later step asks for one. No API key required.

**Inputs**: None.

**Outputs**

- `animation_count` (number): How many are animated GIFs.
- `extension_count` (number): How many distinct extensions the collection uses.
- `extensions` (list): Every extension in the collection with its count, commonest first. These are the values the Only these extensions field takes.
- `kinds` (list): The four kinds of file with their counts, commonest first.
- `other_count` (number): How many are in a format this integration has not seen. Above zero means the collection has grown a format that is reported as other.
- `photo_count` (number): How many are still photographs.
- `total_count` (number): How many dogs there are altogether.
- `video_count` (number): How many are videos.

**Example output**

```json
{
  "animation_count": 39,
  "extension_count": 9,
  "extensions": [
    {
      "content_type": "image/jpeg",
      "count": 742,
      "extension": "jpg",
      "media_kind": "photo",
      "share_percent": 72.0
    }
  ],
  "kinds": [
    {
      "count": 902,
      "media_kind": "photo",
      "share_percent": 87.6
    },
    {
      "count": 89,
      "media_kind": "video",
      "share_percent": 8.6
    },
    {
      "count": 39,
      "media_kind": "animation",
      "share_percent": 3.8
    },
    {
      "count": 0,
      "media_kind": "other",
      "share_percent": 0.0
    }
  ],
  "other_count": 0,
  "photo_count": 902,
  "total_count": 1030,
  "video_count": 89
}
```