API Duckumentation

Endpoint

GET /api/v0/random/

Returns a random duck image from our repository with metadata and attribution information.

Response Format

{
  "id": 123,
  "title": "Duck in a pond",
  "description": "A beautiful mallard swimming in a clear pond",
  "image_url": "https://ducks.now/media/duck_images/2023/04/duck1.jpg",
  "detail_url": "https://ducks.now/duck/123/",
  "attribution_type": "Creative Commons or other permissive license",
  "attribution_name": "Jane Doe",
  "attribution_url": "https://original-source.com",
  "attribution_license": "CC BY 4.0",
  "upload_date": "2023-04-15T14:32:21",
  "view_count": 1245,
  "download_count": 87
}

Response Fields

Field	Type	Description
id	Integer	Unique identifier for the duck image
title	String	Title of the duck image
description	String	Description of the duck image (may be empty)
image_url	String	Direct URL to the duck image
detail_url	String	URL to the duck image's detail page on Ducks.now
attribution_type	String	Type of attribution (e.g., "Self", "Permission", "Creative Commons")
attribution_name	String	Name of the photographer or copyright holder (may be null)
attribution_url	String	URL to the original source or photographer's website (may be null)
attribution_license	String	License identifier (e.g., "CC BY 4.0") (may be null)
upload_date	String	ISO 8601 formatted date when the image was uploaded
view_count	Integer	Number of times the image has been viewed
download_count	Integer	Number of times the image has been downloaded

Example Usage

fetch('https://ducks.now/api/v0/random/')
  .then(response => response.json())
  .then(data => {
    // Display the duck image
    const img = document.createElement('img');
    img.src = data.image_url;
    img.alt = data.title;
    document.body.appendChild(img);
    
    // Add proper attribution
    const attribution = document.createElement('p');
    if (data.attribution_name) {
      attribution.innerHTML = `Photo by: ${data.attribution_name}`;
      if (data.attribution_url) {
        attribution.innerHTML += ` (<a href="${data.attribution_url}" target="_blank">source</a>)`;
      }
    }
    document.body.appendChild(attribution);
    
    // Add license information
    if (data.attribution_license) {
      const license = document.createElement('p');
      license.innerHTML = `License: ${data.attribution_license}`;
      document.body.appendChild(license);
    }
    
    // Add a link back to Ducks.now
    const link = document.createElement('a');
    link.href = data.detail_url;
    link.textContent = "View on Ducks.now";
    link.target = "_blank";
    document.body.appendChild(link);
});

Attribution Requirements

When using images from our API, please respect the attribution requirements:

Include the photographer's name when provided (attribution_name)
Display the license information (attribution_license)
Consider linking back to the image on Ducks.now (detail_url)

Rate Limiting

Please limit your requests to no more than 100 per hour. Excessive requests may be temporarily blocked.