Update app.py

app.py

@@ -1,203 +1,166 @@
-# api.py
-#
-# Flickr API helper for Hugging Face / Gradio image scraper
-#
-# Supports:
-#   1. Flickr search URLs
-#      https://www.flickr.com/search/?text=ai
-#
-#   2. Individual photo URLs
-#      https://www.flickr.com/photos/USERNAME/55555288566/
-#
-#   3. Flickr "with" URLs
-#      https://www.flickr.com/photos/USERNAME/with/55555288566
-#
-# Main date fields:
-#   - publication_date = Flickr upload/post date
-#   - flickr_date_upload
-#   - flickr_date_taken
-#   - flickr_last_update
-#
-# Requires:
-#   FLICKR_API_KEY environment variable
-
 import os
 import re
+import csv
+import io
 import time
-from datetime import datetime, timezone
-from urllib.parse import urlparse, parse_qs, unquote
+import hashlib
+import zipfile
+import tempfile
+import shutil
+import math
+from pathlib import Path
+from urllib.parse import (
+    urlparse,
+    parse_qs,
+    unquote,
+    urljoin,
+)
 
 import requests
+from bs4 import BeautifulSoup
 
+import pandas as pd
+import numpy as np
 
-FLICKR_API_ENDPOINT = "https://www.flickr.com/services/rest/"
+from PIL import Image, ExifTags
 
-FLICKR_API_KEY = os.getenv("FLICKR_API_KEY", "").strip()
+import matplotlib
+matplotlib.use("Agg")
+import matplotlib.pyplot as plt
 
-REQUEST_TIMEOUT = 30
+import gradio as gr
 
-DEFAULT_EXTRAS = ",".join([
-    "description",
-    "license",
-    "date_upload",
-    "date_taken",
-    "owner_name",
-    "icon_server",
-    "original_format",
-    "last_update",
-    "geo",
-    "tags",
-    "machine_tags",
-    "o_dims",
-    "views",
-    "media",
-    "path_alias",
-    "url_sq",
-    "url_t",
-    "url_s",
-    "url_q",
-    "url_m",
-    "url_n",
-    "url_z",
-    "url_c",
-    "url_l",
-    "url_o",
-])
-
-
-# ---------------------------------------------------------------------
-# Basic helpers
-# ---------------------------------------------------------------------
-
-def require_api_key():
-    """
-    Raise a clear error if FLICKR_API_KEY is not configured.
-    """
-    if not FLICKR_API_KEY:
-        raise RuntimeError(
-            "FLICKR_API_KEY is not configured. "
-            "Add it as a Hugging Face Space Secret."
-        )
 
+# ============================================================
+# CONFIGURATION
+# ============================================================
 
-def flickr_timestamp_to_utc(value):
-    """
-    Convert Flickr Unix timestamp to UTC datetime string.
+APP_TITLE = "Web & Flickr Image Downloader + Metadata"
 
-    Flickr's 'posted' / 'dateupload' timestamps are Unix timestamps
-    expressed in GMT/UTC.
-    """
-    if value in (None, "", 0, "0"):
-        return None
+MAX_IMAGES_HARD_LIMIT = 500
 
-    try:
-        dt = datetime.fromtimestamp(
-            int(float(value)),
-            tz=timezone.utc
-        )
+REQUEST_TIMEOUT = 30
+IMAGE_TIMEOUT = 45
 
-        return dt.strftime("%Y-%m-%d %H:%M:%S UTC")
+USER_AGENT = (
+    "Mozilla/5.0 (Windows NT 10.0; Win64; x64) "
+    "AppleWebKit/537.36 (KHTML, like Gecko) "
+    "Chrome/140.0 Safari/537.36"
+)
 
-    except Exception:
-        return None
+HEADERS = {
+    "User-Agent": USER_AGENT,
+    "Accept": (
+        "text/html,application/xhtml+xml,"
+        "application/xml;q=0.9,"
+        "image/avif,image/webp,image/apng,"
+        "*/*;q=0.8"
+    ),
+    "Accept-Language": "en-US,en;q=0.9,fr;q=0.8",
+}
 
 
-def flickr_taken_to_string(value):
-    """
-    Flickr's date taken is already a MySQL-style datetime.
+# ============================================================
+# TEMPORARY STORAGE
+# ============================================================
 
-    IMPORTANT:
-    We do not convert this timezone because Flickr states that
-    taken dates are represented in the photo owner's timezone.
-    """
-    if not value:
-        return None
+BASE_DIR = (
+    Path(tempfile.gettempdir())
+    / "gradio_web_image_downloader"
+)
 
-    value = str(value).strip()
+BASE_DIR.mkdir(
+    parents=True,
+    exist_ok=True
+)
 
-    if value in ("0000-00-00 00:00:00", "0000-00-00"):
-        return None
 
-    return value
+# ============================================================
+# FLICKR API
+# ============================================================
 
+FLICKR_API_KEY = (
+    os.environ
+    .get("FLICKR_API_KEY", "")
+    .strip()
+)
 
-def extract_flickr_photo_id(url):
-    """
-    Extract a Flickr photo ID from URLs such as:
+FLICKR_API_URL = (
+    "https://api.flickr.com/services/rest/"
+)
 
-        /photos/user/55555288566/
-        /photos/user/with/55555288566
-        /photos/user/55555288566/in/dateposted/
-    """
 
-    if not url:
-        return None
+# ============================================================
+# HTTP SESSION
+# ============================================================
 
-    try:
-        parsed = urlparse(url)
-        path = unquote(parsed.path)
+session = requests.Session()
+session.headers.update(HEADERS)
 
-        # /photos/user/with/55555288566
-        match = re.search(
-            r"/photos/[^/]+/with/(\d+)",
-            path,
-            flags=re.IGNORECASE
-        )
 
-        if match:
-            return match.group(1)
+# ============================================================
+# EXIF TAGS
+# ============================================================
 
-        # /photos/user/55555288566
-        match = re.search(
-            r"/photos/[^/]+/(\d+)",
-            path,
-            flags=re.IGNORECASE
-        )
+EXIF_TAGS = {
+    tag_id: tag_name
+    for tag_id, tag_name
+    in ExifTags.TAGS.items()
+}
 
-        if match:
-            return match.group(1)
 
-    except Exception:
-        pass
+GPS_TAGS = {
+    tag_id: tag_name
+    for tag_id, tag_name
+    in ExifTags.GPSTAGS.items()
+}
 
-    return None
 
+# ============================================================
+# HELPERS
+# ============================================================
 
-def extract_flickr_username(url):
-    """
-    Extract username/path alias from a Flickr photo URL.
-    """
+def clean_url(url):
     if not url:
-        return None
+        return ""
 
+    url = str(url).strip()
+
+    if not url:
+        return ""
+
+    if not url.startswith(
+        ("http://", "https://")
+    ):
+        url = "https://" + url
+
+    return url
+
+
+def valid_http_url(url):
     try:
+
         parsed = urlparse(url)
-        path = unquote(parsed.path)
 
-        match = re.search(
-            r"/photos/([^/]+)/",
-            path,
-            flags=re.IGNORECASE
+        return (
+            parsed.scheme in
+            ("http", "https")
+            and bool(parsed.netloc)
         )
 
-        if match:
-            return match.group(1)
-
     except Exception:
-        pass
 
-    return None
+        return False
 
 
 def is_flickr_url(url):
-    """
-    True for Flickr URLs.
-    """
-    if not url:
-        return False
-
     try:
-        host = urlparse(url).netloc.lower()
+
+        host = (
+            urlparse(url)
+            .netloc
+            .lower()
+        )
 
         return (
             host == "flickr.com"
@@ -205,903 +168,3125 @@ def is_flickr_url(url):
         )
 
     except Exception:
+
         return False
 
 
 def extract_flickr_search_text(url):
-    """
-    Extract ?text=... from Flickr search URLs.
-    """
-    if not url:
-        return None
 
     try:
+
         parsed = urlparse(url)
-        params = parse_qs(parsed.query)
 
-        text = params.get("text", [None])[0]
+        query = parse_qs(
+            parsed.query
+        )
+
+        text = query.get(
+            "text",
+            [""]
+        )[0]
 
-        if text:
-            return unquote(text).strip()
+        return unquote(
+            text
+        ).strip()
 
     except Exception:
-        pass
 
-    return None
+        return ""
 
 
-# ---------------------------------------------------------------------
-# API request
-# ---------------------------------------------------------------------
+def safe_filename(
+    value,
+    default="image"
+):
 
-def flickr_api_call(method, params=None, retries=3):
-    """
-    Generic Flickr REST API call.
+    if not value:
+        value = default
 
-    Returns decoded JSON.
+    value = str(value)
 
-    Raises RuntimeError with useful information on API errors.
-    """
+    value = re.sub(
+        r'[<>:"/\\|?*\x00-\x1f]',
+        "_",
+        value
+    )
 
-    require_api_key()
+    value = value.strip(
+        " ."
+    )
 
-    payload = {
-        "method": method,
-        "api_key": FLICKR_API_KEY,
-        "format": "json",
-        "nojsoncallback": 1,
-    }
+    if not value:
+        value = default
 
-    if params:
-        payload.update(params)
+    return value[:180]
 
-    last_error = None
 
-    for attempt in range(1, retries + 1):
+def make_hash(value):
 
-        try:
+    return hashlib.sha1(
+        value.encode(
+            "utf-8",
+            errors="ignore"
+        )
+    ).hexdigest()[:12]
 
-            response = requests.get(
-                FLICKR_API_ENDPOINT,
-                params=payload,
-                timeout=REQUEST_TIMEOUT,
-                headers={
-                    "User-Agent": (
-                        "Mozilla/5.0 "
-                        "(compatible; FlickrResearchImageDownloader/1.0)"
-                    )
-                },
-            )
 
-            response.raise_for_status()
+def extension_from_content_type(
+    content_type
+):
 
-            data = response.json()
+    if not content_type:
+        return ".jpg"
 
-            if data.get("stat") != "ok":
+    content_type = (
+        content_type
+        .lower()
+    )
 
-                code = data.get("code", "unknown")
+    mapping = {
 
-                message = data.get(
-                    "message",
-                    "Unknown Flickr API error"
-                )
+        "image/jpeg": ".jpg",
+        "image/jpg": ".jpg",
+        "image/png": ".png",
+        "image/webp": ".webp",
+        "image/gif": ".gif",
+        "image/bmp": ".bmp",
+        "image/tiff": ".tif",
+        "image/avif": ".avif",
 
-                raise RuntimeError(
-                    f"Flickr API error {code}: {message}"
-                )
+    }
 
-            return data
+    return mapping.get(
+        content_type.split(";")[0],
+        ".jpg"
+    )
 
-        except Exception as exc:
 
-            last_error = exc
+# ============================================================
+# DATE HELPERS
+# ============================================================
 
-            if attempt < retries:
-                time.sleep(1.5 * attempt)
+def parse_date(value):
 
-    raise RuntimeError(
-        f"Flickr API request failed after {retries} attempts: "
-        f"{last_error}"
-    )
+    if value is None:
+        return pd.NaT
 
+    if isinstance(
+        value,
+        pd.Timestamp
+    ):
+        return value
 
-# ---------------------------------------------------------------------
-# Photo normalization
-# ---------------------------------------------------------------------
+    if isinstance(
+        value,
+        (int, float)
+    ):
 
-def choose_best_flickr_image_url(photo):
-    """
-    Select the highest available Flickr image URL.
-    """
+        if value > 100000000000:
 
-    # Highest → lowest priority
-    candidates = [
-        "url_o",
-        "url_l",
-        "url_c",
-        "url_z",
-        "url_n",
-        "url_m",
-        "url_q",
-        "url_s",
-        "url_t",
-    ]
+            return pd.to_datetime(
+                value,
+                unit="ms",
+                errors="coerce"
+            )
 
-    for field in candidates:
+        if value > 1000000000:
 
-        value = photo.get(field)
+            return pd.to_datetime(
+                value,
+                unit="s",
+                errors="coerce"
+            )
 
-        if value:
-            return value
+    value = str(value).strip()
 
-    return None
+    if not value:
+        return pd.NaT
 
+    # EXIF format:
+    # 2025:09:28 14:32:11
 
-def build_flickr_photo_record(photo):
-    """
-    Convert Flickr API photo object into the standardized metadata
-    structure used by the scraper.
-    """
+    if re.match(
+        r"^\d{4}:\d{2}:\d{2}",
+        value
+    ):
 
-    photo_id = str(photo.get("id", "")).strip()
+        try:
 
-    owner_id = photo.get("owner")
+            return pd.to_datetime(
+                value,
+                format="%Y:%m:%d %H:%M:%S",
+                errors="coerce"
+            )
 
-    owner_name = photo.get("ownername")
+        except Exception:
+            pass
 
-    title = photo.get("title", "")
+    return pd.to_datetime(
+        value,
+        errors="coerce"
+    )
 
-    description = photo.get("description", "")
 
-    if isinstance(description, dict):
-        description = description.get("_content", "")
+def iso_or_empty(value):
 
-    image_url = choose_best_flickr_image_url(photo)
+    dt = parse_date(value)
 
-    # -------------------------------------------------------------
-    # Dates
-    # -------------------------------------------------------------
+    if pd.isna(dt):
+        return ""
 
-    date_upload_raw = photo.get("dateupload")
+    return dt.strftime(
+        "%Y-%m-%d %H:%M:%S"
+    )
 
-    date_taken_raw = photo.get("datetaken")
 
-    last_update_raw = photo.get("lastupdate")
+# ============================================================
+# GPS HELPERS
+# ============================================================
 
-    flickr_date_upload = flickr_timestamp_to_utc(
-        date_upload_raw
-    )
+def gps_to_decimal(value, ref=None):
 
-    flickr_date_taken = flickr_taken_to_string(
-        date_taken_raw
-    )
+    try:
 
-    flickr_last_update = flickr_timestamp_to_utc(
-        last_update_raw
-    )
+        if value is None:
+            return None
 
-    # Publication date means upload/post date.
-    publication_date = flickr_date_upload
+        if isinstance(
+            value,
+            (list, tuple)
+        ):
 
-    # -------------------------------------------------------------
-    # Dimensions
-    # -------------------------------------------------------------
+            if len(value) != 3:
+                return None
 
-    width = photo.get("width_o")
+            def convert_component(x):
 
-    height = photo.get("height_o")
+                if hasattr(
+                    x,
+                    "numerator"
+                ):
 
-    if not width:
-        width = photo.get("width_l")
+                    return (
+                        float(x.numerator)
+                        / float(x.denominator)
+                    )
 
-    if not height:
-        height = photo.get("height_l")
+                if isinstance(
+                    x,
+                    tuple
+                ) and len(x) == 2:
 
-    # Some API responses provide o_dims="1234x5678"
-    if (not width or not height) and photo.get("o_dims"):
+                    return (
+                        float(x[0])
+                        / float(x[1])
+                    )
 
-        try:
-            dimensions = str(photo["o_dims"])
+                return float(x)
 
-            match = re.match(
-                r"^\s*(\d+)\s*x\s*(\d+)\s*$",
-                dimensions
+            degrees = convert_component(
+                value[0]
             )
 
-            if match:
-                width = int(match.group(1))
-                height = int(match.group(2))
+            minutes = convert_component(
+                value[1]
+            )
 
-        except Exception:
-            pass
+            seconds = convert_component(
+                value[2]
+            )
 
-    # -------------------------------------------------------------
-    # Photo page
-    # -------------------------------------------------------------
+            decimal = (
+                degrees
+                + minutes / 60
+                + seconds / 3600
+            )
 
-    photo_page_url = (
-        f"https://www.flickr.com/photos/"
-        f"{owner_id}/{photo_id}/"
-        if owner_id and photo_id
-        else None
-    )
+            if ref in ("S", "W"):
+                decimal = -decimal
 
-    # -------------------------------------------------------------
-    # Tags
-    # -------------------------------------------------------------
+            return decimal
 
-    tags = photo.get("tags", "")
+        return None
 
-    if isinstance(tags, list):
-        tags = ", ".join(
-            str(x) for x in tags
-        )
+    except Exception:
 
-    # -------------------------------------------------------------
-    # Geographic information
-    # -------------------------------------------------------------
+        return None
 
-    latitude = photo.get("latitude")
 
-    longitude = photo.get("longitude")
+# ============================================================
+# EXIF EXTRACTION
+# ============================================================
 
-    try:
-        latitude = float(latitude) if latitude not in (None, "") else None
-    except Exception:
-        latitude = None
+def extract_exif_metadata(
+    image
+):
 
-    try:
-        longitude = (
-            float(longitude)
-            if longitude not in (None, "")
-            else None
-        )
-    except Exception:
-        longitude = None
+    metadata = {
+
+        "exif_make": "",
+        "exif_model": "",
+        "exif_software": "",
+        "exif_datetime": "",
+        "exif_datetime_original": "",
+        "exif_datetime_digitized": "",
+        "exif_orientation": "",
+        "exif_lens_model": "",
+        "exif_focal_length": "",
+        "exif_iso": "",
+        "exif_exposure_time": "",
+        "exif_f_number": "",
+        "exif_gps_latitude": "",
+        "exif_gps_longitude": "",
+        "exif_gps_altitude": "",
 
-    # -------------------------------------------------------------
-    # Result
-    # -------------------------------------------------------------
+    }
 
-    record = {
+    try:
 
-        # Identification
-        "source": "Flickr API",
-        "flickr_photo_id": photo_id,
-        "flickr_owner_id": owner_id,
-        "flickr_owner_name": owner_name,
+        exif = image.getexif()
 
-        # URLs
-        "url": image_url,
-        "image_url": image_url,
-        "page_url": photo_page_url,
+        if not exif:
+            return metadata
 
-        # Basic metadata
-        "title": title,
-        "description": description,
+        decoded = {}
 
-        # Dates
-        "publication_date": publication_date,
-        "publication_date_source": (
-            "Flickr API dateupload"
-            if publication_date
-            else None
-        ),
-
-        "flickr_date_upload": flickr_date_upload,
-        "flickr_date_upload_timestamp": date_upload_raw,
-
-        "flickr_date_taken": flickr_date_taken,
-        "flickr_date_taken_granularity": (
-            photo.get("datetakengranularity")
-        ),
-
-        "flickr_last_update": flickr_last_update,
-        "flickr_last_update_timestamp": last_update_raw,
-
-        # Image
-        "width": width,
-        "height": height,
-        "original_format": photo.get("originalformat"),
-        "media": photo.get("media"),
-
-        # Flickr statistics
-        "views": photo.get("views"),
-        "license": photo.get("license"),
-
-        # Tags
-        "tags": tags,
-        "machine_tags": photo.get("machine_tags"),
-
-        # Location
-        "latitude": latitude,
-        "longitude": longitude,
-
-        # Download fields populated later
-        "local_file": None,
-        "filename": None,
-        "file_size": None,
-        "final_url": image_url,
-        "download_status": None,
+        for key, value in exif.items():
 
-    }
+            name = EXIF_TAGS.get(
+                key,
+                str(key)
+            )
 
-    return record
+            decoded[name] = value
 
+        metadata[
+            "exif_make"
+        ] = str(
+            decoded.get(
+                "Make",
+                ""
+            )
+        )
 
-# ---------------------------------------------------------------------
-# Get one Flickr photo
-# ---------------------------------------------------------------------
+        metadata[
+            "exif_model"
+        ] = str(
+            decoded.get(
+                "Model",
+                ""
+            )
+        )
 
-def flickr_get_photo(photo_id):
-    """
-    Retrieve complete metadata for one Flickr photo.
+        metadata[
+            "exif_software"
+        ] = str(
+            decoded.get(
+                "Software",
+                ""
+            )
+        )
 
-    Uses:
-        flickr.photos.getInfo
-    """
+        metadata[
+            "exif_datetime"
+        ] = str(
+            decoded.get(
+                "DateTime",
+                ""
+            )
+        )
 
-    if not photo_id:
-        raise ValueError("Missing Flickr photo ID.")
+        metadata[
+            "exif_datetime_original"
+        ] = str(
+            decoded.get(
+                "DateTimeOriginal",
+                ""
+            )
+        )
 
-    data = flickr_api_call(
-        "flickr.photos.getInfo",
-        {
-            "photo_id": str(photo_id),
-        }
-    )
+        metadata[
+            "exif_datetime_digitized"
+        ] = str(
+            decoded.get(
+                "DateTimeDigitized",
+                ""
+            )
+        )
 
-    photo = data.get("photo")
+        metadata[
+            "exif_orientation"
+        ] = str(
+            decoded.get(
+                "Orientation",
+                ""
+            )
+        )
 
-    if not photo:
-        raise RuntimeError(
-            f"No photo data returned for Flickr ID {photo_id}"
+        metadata[
+            "exif_lens_model"
+        ] = str(
+            decoded.get(
+                "LensModel",
+                ""
+            )
         )
 
-    # getInfo has a nested structure which differs from search.
-    normalized = {
-        "id": photo.get("id"),
+        # Focal length
 
-        "owner": (
-            photo.get("owner", {}).get("nsid")
-            if isinstance(photo.get("owner"), dict)
-            else None
-        ),
+        focal = decoded.get(
+            "FocalLength"
+        )
 
-        "ownername": (
-            photo.get("owner", {}).get("username")
-            if isinstance(photo.get("owner"), dict)
-            else None
-        ),
+        if focal is not None:
 
-        "title": (
-            photo.get("title", {}).get("_content", "")
-            if isinstance(photo.get("title"), dict)
-            else photo.get("title", "")
-        ),
+            try:
 
-        "description": (
-            photo.get("description", {}).get("_content", "")
-            if isinstance(photo.get("description"), dict)
-            else photo.get("description", "")
-        ),
+                if hasattr(
+                    focal,
+                    "numerator"
+                ):
 
-        "license": photo.get("license"),
+                    metadata[
+                        "exif_focal_length"
+                    ] = round(
+                        float(
+                            focal.numerator
+                        )
+                        /
+                        float(
+                            focal.denominator
+                        ),
+                        2
+                    )
 
-        "rotation": photo.get("rotation"),
+                else:
 
-        "originalformat": photo.get("originalformat"),
+                    metadata[
+                        "exif_focal_length"
+                    ] = str(
+                        focal
+                    )
 
-    }
+            except Exception:
 
-    # -------------------------------------------------------------
-    # Dates from <dates ... />
-    # -------------------------------------------------------------
+                metadata[
+                    "exif_focal_length"
+                ] = str(
+                    focal
+                )
 
-    dates = photo.get("dates", {})
+        metadata[
+            "exif_iso"
+        ] = str(
+            decoded.get(
+                "ISOSpeedRatings",
+                decoded.get(
+                    "PhotographicSensitivity",
+                    ""
+                )
+            )
+        )
 
-    if isinstance(dates, dict):
+        metadata[
+            "exif_exposure_time"
+        ] = str(
+            decoded.get(
+                "ExposureTime",
+                ""
+            )
+        )
 
-        normalized["dateupload"] = dates.get("posted")
+        metadata[
+            "exif_f_number"
+        ] = str(
+            decoded.get(
+                "FNumber",
+                ""
+            )
+        )
 
-        normalized["datetaken"] = dates.get("taken")
+        # ----------------------------------------------------
+        # GPS
+        # ----------------------------------------------------
 
-        normalized["datetakengranularity"] = dates.get(
-            "takengranularity"
+        gps_info = decoded.get(
+            "GPSInfo"
         )
 
-        normalized["lastupdate"] = dates.get(
-            "lastupdate"
-        )
+        if gps_info:
 
-    # -------------------------------------------------------------
-    # URLs
-    # -------------------------------------------------------------
+            gps_decoded = {}
 
-    urls = photo.get("urls", {}).get("url", [])
+            try:
 
-    photo_page_url = None
+                for key, value in gps_info.items():
 
-    if isinstance(urls, list):
+                    gps_name = GPS_TAGS.get(
+                        key,
+                        str(key)
+                    )
 
-        for item in urls:
+                    gps_decoded[
+                        gps_name
+                    ] = value
 
-            if (
-                isinstance(item, dict)
-                and item.get("type") == "photopage"
-            ):
-                photo_page_url = item.get("_content")
-                break
+            except Exception:
+                gps_decoded = {}
 
-    normalized["photo_page_url"] = photo_page_url
+            lat = gps_decoded.get(
+                "GPSLatitude"
+            )
 
-    # -------------------------------------------------------------
-    # Tags
-    # -------------------------------------------------------------
+            lat_ref = gps_decoded.get(
+                "GPSLatitudeRef"
+            )
 
-    tag_list = photo.get("tags", {}).get("tag", [])
+            lon = gps_decoded.get(
+                "GPSLongitude"
+            )
 
-    tags = []
+            lon_ref = gps_decoded.get(
+                "GPSLongitudeRef"
+            )
 
-    if isinstance(tag_list, list):
+            lat_decimal = gps_to_decimal(
+                lat,
+                lat_ref
+            )
 
-        for tag in tag_list:
+            lon_decimal = gps_to_decimal(
+                lon,
+                lon_ref
+            )
 
-            if isinstance(tag, dict):
+            if lat_decimal is not None:
 
-                raw = tag.get("raw")
+                metadata[
+                    "exif_gps_latitude"
+                ] = round(
+                    lat_decimal,
+                    7
+                )
 
-                content = tag.get("_content")
+            if lon_decimal is not None:
 
-                tags.append(
-                    raw or content or ""
+                metadata[
+                    "exif_gps_longitude"
+                ] = round(
+                    lon_decimal,
+                    7
                 )
 
-    normalized["tags"] = ", ".join(
-        x for x in tags if x
-    )
+            altitude = gps_decoded.get(
+                "GPSAltitude"
+            )
 
-    # -------------------------------------------------------------
-    # Location
-    # -------------------------------------------------------------
+            if altitude is not None:
 
-    location = photo.get("location", {})
+                try:
 
-    if isinstance(location, dict):
+                    if hasattr(
+                        altitude,
+                        "numerator"
+                    ):
+
+                        metadata[
+                            "exif_gps_altitude"
+                        ] = round(
+                            float(
+                                altitude.numerator
+                            )
+                            /
+                            float(
+                                altitude.denominator
+                            ),
+                            2
+                        )
+
+                    else:
+
+                        metadata[
+                            "exif_gps_altitude"
+                        ] = str(
+                            altitude
+                        )
 
-        normalized["latitude"] = location.get("latitude")
+                except Exception:
 
-        normalized["longitude"] = location.get("longitude")
+                    metadata[
+                        "exif_gps_altitude"
+                    ] = str(
+                        altitude
+                    )
 
-    # -------------------------------------------------------------
-    # Get image URL through the size API
-    # -------------------------------------------------------------
+    except Exception:
 
-    try:
+        pass
 
-        sizes_data = flickr_api_call(
-            "flickr.photos.getSizes",
-            {
-                "photo_id": str(photo_id)
-            }
-        )
+    return metadata
 
-        sizes = (
-            sizes_data
-            .get("sizes", {})
-            .get("size", [])
-        )
 
-        best_url = None
-        best_width = None
-        best_height = None
+# ============================================================
+# FLICKR API
+# ============================================================
 
-        if isinstance(sizes, list):
+def flickr_search(
+    search_text,
+    max_images=50,
+    min_width=0,
+    min_height=0,
+):
 
-            for size in sizes:
+    if not FLICKR_API_KEY:
 
-                if not isinstance(size, dict):
-                    continue
+        raise RuntimeError(
+            "No FLICKR_API_KEY was found. "
+            "Add FLICKR_API_KEY under "
+            "Space Settings → Secrets."
+        )
 
-                source = size.get("source")
+    search_text = (
+        search_text
+        .strip()
+    )
 
-                if not source:
-                    continue
+    if not search_text:
 
-                try:
-                    w = int(size.get("width", 0))
-                except Exception:
-                    w = 0
+        raise ValueError(
+            "No Flickr search term was found."
+        )
 
-                try:
-                    h = int(size.get("height", 0))
-                except Exception:
-                    h = 0
+    max_images = min(
+        int(max_images),
+        MAX_IMAGES_HARD_LIMIT
+    )
 
-                if (
-                    best_width is None
-                    or w * h > best_width * best_height
-                ):
-                    best_url = source
-                    best_width = w
-                    best_height = h
+    results = []
 
-        normalized["url_o"] = best_url
-        normalized["width_o"] = best_width
-        normalized["height_o"] = best_height
+    page = 1
 
-    except Exception as exc:
+    per_page = min(
+        500,
+        max(
+            100,
+            max_images
+        )
+    )
 
-        normalized["url_o"] = None
-        normalized["width_o"] = None
-        normalized["height_o"] = None
+    while len(results) < max_images:
+
+        params = {
+
+            "method":
+                "flickr.photos.search",
+
+            "api_key":
+                FLICKR_API_KEY,
+
+            "text":
+                search_text,
+
+            "format":
+                "json",
+
+            "nojsoncallback":
+                "1",
+
+            "safe_search":
+                "1",
+
+            "extras": (
+                "description,"
+                "license,"
+                "date_upload,"
+                "date_taken,"
+                "owner_name,"
+                "tags,"
+                "views,"
+                "url_sq,"
+                "url_t,"
+                "url_s,"
+                "url_q,"
+                "url_m,"
+                "url_n,"
+                "url_z,"
+                "url_c,"
+                "url_l,"
+                "url_o,"
+                "o_dims,"
+                "original_format"
+            ),
+
+            "per_page":
+                per_page,
+
+            "page":
+                page,
+        }
 
-        normalized["_sizes_error"] = str(exc)
+        response = session.get(
+            FLICKR_API_URL,
+            params=params,
+            timeout=REQUEST_TIMEOUT,
+        )
 
-    return build_flickr_photo_record(normalized)
+        response.raise_for_status()
 
+        data = response.json()
 
-# ---------------------------------------------------------------------
-# Flickr search
-# ---------------------------------------------------------------------
+        if data.get("stat") != "ok":
 
-def flickr_search(
-    text=None,
-    user_id=None,
-    tags=None,
-    max_images=100,
-    sort="date-posted-desc",
-):
-    """
-    Search Flickr photos.
+            message = data.get(
+                "message",
+                "Unknown Flickr API error."
+            )
 
-    Parameters
-    ----------
-    text:
-        Flickr free-text search.
+            raise RuntimeError(
+                f"Flickr API error: {message}"
+            )
 
-    user_id:
-        Flickr NSID if searching a specific account.
+        photos = data.get(
+            "photos",
+            {}
+        )
 
-    tags:
-        Flickr tag search.
+        photo_list = photos.get(
+            "photo",
+            []
+        )
 
-    max_images:
-        Maximum number of returned photos.
+        if not photo_list:
+            break
 
-    sort:
-        Flickr sorting mode.
+        for photo in photo_list:
 
-    Returns
-    -------
-    list[dict]
-    """
+            candidate_fields = [
 
-    require_api_key()
+                "url_o",
+                "url_l",
+                "url_c",
+                "url_z",
+                "url_n",
+                "url_m",
+                "url_s",
+                "url_q",
+                "url_t",
 
-    max_images = max(
-        1,
-        min(int(max_images), 500)
-    )
+            ]
 
-    data = flickr_api_call(
-        "flickr.photos.search",
-        {
-            "text": text or "",
-            "user_id": user_id or "",
-            "tags": tags or "",
-            "sort": sort,
-            "media": "all",
-            "per_page": max_images,
-            "page": 1,
-            "extras": DEFAULT_EXTRAS,
-        }
-    )
+            image_url = None
 
-    photos_container = data.get(
-        "photos",
-        {}
-    )
+            for field in candidate_fields:
 
-    photos = photos_container.get(
-        "photo",
-        []
-    )
+                if photo.get(field):
 
-    results = []
+                    image_url = (
+                        photo[field]
+                    )
 
-    for photo in photos:
+                    break
 
-        try:
+            if not image_url:
+                continue
 
-            record = build_flickr_photo_record(
-                photo
+            width = (
+                photo.get("width_o")
+                or photo.get("width_l")
+                or photo.get("width_c")
+                or photo.get("width_z")
+                or 0
             )
 
-            if record.get("url"):
+            height = (
+                photo.get("height_o")
+                or photo.get("height_l")
+                or photo.get("height_c")
+                or photo.get("height_z")
+                or 0
+            )
 
-                results.append(record)
+            try:
+                width = int(width or 0)
+            except Exception:
+                width = 0
 
-        except Exception as exc:
+            try:
+                height = int(height or 0)
+            except Exception:
+                height = 0
 
-            # Keep failed API records instead of crashing
-            results.append({
-                "source": "Flickr API",
-                "download_status": (
-                    f"metadata_error: {exc}"
-                ),
-            })
+            if (
+                min_width
+                and width
+                and width < min_width
+            ):
+                continue
 
-    return results
+            if (
+                min_height
+                and height
+                and height < min_height
+            ):
+                continue
 
+            photo_id = str(
+                photo.get(
+                    "id",
+                    ""
+                )
+            )
 
-# ---------------------------------------------------------------------
-# Parse Flickr URL
-# ---------------------------------------------------------------------
+            page_url = (
+                "https://www.flickr.com/photos/"
+                f"{photo.get('owner', '')}/"
+                f"{photo_id}/"
+            )
 
-def parse_flickr_url(url):
-    """
-    Determine what type of Flickr URL we have.
+            results.append(
+                {
+
+                    "image_url":
+                        image_url,
+
+                    "page_url":
+                        page_url,
+
+                    "title":
+                        photo.get(
+                            "title",
+                            ""
+                        ),
+
+                    "owner":
+                        photo.get(
+                            "ownername",
+                            ""
+                        ),
+
+                    "photo_id":
+                        photo_id,
+
+                    "width":
+                        width,
+
+                    "height":
+                        height,
+
+                    "source":
+                        "Flickr API",
+
+                    "license":
+                        photo.get(
+                            "license",
+                            ""
+                        ),
+
+                    "date_taken":
+                        photo.get(
+                            "datetaken",
+                            ""
+                        ),
+
+                    "date_uploaded":
+                        photo.get(
+                            "dateupload",
+                            ""
+                        ),
+
+                    "views":
+                        photo.get(
+                            "views",
+                            ""
+                        ),
+
+                    "tags":
+                        photo.get(
+                            "tags",
+                            ""
+                        ),
+
+                    "description":
+                        photo.get(
+                            "description",
+                            ""
+                        ),
+
+                    "alt":
+                        "",
+
+                }
+            )
 
-    Returns:
+            if len(results) >= max_images:
+                break
 
-        {
-            "type": "photo",
-            "photo_id": "...",
-            "username": "..."
-        }
+        total_pages = int(
+            photos.get(
+                "pages",
+                page
+            )
+        )
 
-    or
+        if page >= total_pages:
+            break
 
-        {
-            "type": "search",
-            "text": "..."
-        }
+        page += 1
 
-    """
+    return results
 
-    if not is_flickr_url(url):
 
-        return {
-            "type": "unknown",
-            "photo_id": None,
-            "username": None,
-            "text": None,
-        }
+# ============================================================
+# GENERIC HTML EXTRACTION
+# ============================================================
 
-    photo_id = extract_flickr_photo_id(url)
+def extract_image_candidates_from_html(
+    page_url,
+    html,
+):
 
-    if photo_id:
+    soup = BeautifulSoup(
+        html,
+        "html.parser"
+    )
 
-        return {
-            "type": "photo",
-            "photo_id": photo_id,
-            "username": extract_flickr_username(url),
-            "text": None,
-        }
+    candidates = []
 
-    text = extract_flickr_search_text(url)
+    # --------------------------------------------------------
+    # IMG
+    # --------------------------------------------------------
 
-    if text:
+    for img in soup.find_all(
+        "img"
+    ):
 
-        return {
-            "type": "search",
-            "photo_id": None,
-            "username": None,
-            "text": text,
-        }
+        attributes = [
 
-    # Generic Flickr search URL without text
-    parsed = urlparse(url)
+            "src",
+            "data-src",
+            "data-original",
+            "data-lazy-src",
+            "data-image",
+            "data-url",
+            "data-srcset",
 
-    if "/search" in parsed.path.lower():
+        ]
 
-        return {
-            "type": "search",
-            "photo_id": None,
-            "username": None,
-            "text": None,
-        }
+        for attribute in attributes:
 
-    return {
-        "type": "unknown",
-        "photo_id": None,
-        "username": None,
-        "text": None,
-    }
+            value = img.get(
+                attribute
+            )
 
+            if not value:
+                continue
 
-# ---------------------------------------------------------------------
-# Main URL handler
-# ---------------------------------------------------------------------
+            if attribute == "data-srcset":
 
-def flickr_from_url(
-    url,
-    max_images=100,
-):
-    """
-    Main entry point.
+                parts = [
+                    p.strip()
+                    for p in value.split(",")
+                ]
 
-    Automatically decides whether to use:
+                for part in parts:
 
-        flickr.photos.getInfo
+                    pieces = (
+                        part.split()
+                    )
 
-    or:
+                    if pieces:
 
-        flickr.photos.search
-    """
+                        candidates.append(
+                            (
+                                pieces[0],
+                                img.get(
+                                    "alt",
+                                    ""
+                                )
+                            )
+                        )
 
-    parsed = parse_flickr_url(url)
+            else:
 
-    url_type = parsed["type"]
+                candidates.append(
+                    (
+                        value,
+                        img.get(
+                            "alt",
+                            ""
+                        )
+                    )
+                )
 
-    # -------------------------------------------------------------
-    # Individual photo / /with/ URL
-    # -------------------------------------------------------------
+    # --------------------------------------------------------
+    # SOURCE SRCSET
+    # --------------------------------------------------------
 
-    if url_type == "photo":
+    for source in soup.find_all(
+        "source"
+    ):
 
-        record = flickr_get_photo(
-            parsed["photo_id"]
+        srcset = source.get(
+            "srcset"
         )
 
-        return [record]
+        if not srcset:
+            continue
 
-    # -------------------------------------------------------------
-    # Search URL
-    # -------------------------------------------------------------
+        for part in srcset.split(","):
 
-    if url_type == "search":
+            pieces = (
+                part.strip()
+                .split()
+            )
 
-        return flickr_search(
-            text=parsed.get("text"),
-            max_images=max_images,
-        )
+            if pieces:
 
-    raise ValueError(
-        "The Flickr URL could not be recognized. "
-        "Supported formats include Flickr search URLs, "
-        "individual photo URLs, and /with/PHOTO_ID URLs."
-    )
+                candidates.append(
+                    (
+                        pieces[0],
+                        ""
+                    )
+                )
 
+    # --------------------------------------------------------
+    # OG IMAGE
+    # --------------------------------------------------------
 
-# ---------------------------------------------------------------------
-# Convenience function for your app.py
-# ---------------------------------------------------------------------
+    for meta in soup.find_all(
+        "meta",
+        attrs={
+            "property": "og:image"
+        }
+    ):
 
-def get_flickr_images(
-    url,
-    max_images=100,
-):
-    """
-    Compatibility wrapper.
+        value = meta.get(
+            "content"
+        )
 
-    Your app.py can simply call:
+        if value:
 
-        records = get_flickr_images(url, max_images)
+            candidates.append(
+                (
+                    value,
+                    "og:image"
+                )
+            )
 
-    """
+    # --------------------------------------------------------
+    # Resolve URLs
+    # --------------------------------------------------------
 
-    return flickr_from_url(
-        url=url,
-        max_images=max_images,
-    )
+    resolved = []
 
+    for value, alt in candidates:
 
-# ---------------------------------------------------------------------
-# Test / diagnostics
-# ---------------------------------------------------------------------
+        if not value:
+            continue
 
-def diagnose_flickr_url(url):
-    """
-    Return diagnostic information without downloading images.
-    Useful for debugging a Hugging Face Space.
-    """
+        value = value.strip()
 
-    result = {
-        "url": url,
-        "is_flickr": is_flickr_url(url),
-        "url_type": None,
-        "photo_id": None,
-        "username": None,
-        "search_text": None,
-        "api_key_configured": bool(FLICKR_API_KEY),
-    }
+        if value.startswith(
+            "data:"
+        ):
+            continue
 
-    parsed = parse_flickr_url(url)
+        absolute = urljoin(
+            page_url,
+            value
+        )
 
-    result["url_type"] = parsed.get("type")
-    result["photo_id"] = parsed.get("photo_id")
-    result["username"] = parsed.get("username")
-    result["search_text"] = parsed.get("text")
+        if not valid_http_url(
+            absolute
+        ):
+            continue
 
-    return result
+        resolved.append(
+            {
 
+                "image_url":
+                    absolute,
 
-# ---------------------------------------------------------------------
-# Direct test
-# ---------------------------------------------------------------------
+                "page_url":
+                    page_url,
 
-if __name__ == "__main__":
+                "title":
+                    "",
 
-    TEST_URL = (
-        "https://www.flickr.com/"
-        "photos/snapnpiks0304/"
-        "with/55555288566"
-    )
+                "owner":
+                    "",
 
-    print("=" * 70)
-    print("FLICKR API TEST")
-    print("=" * 70)
+                "photo_id":
+                    "",
 
-    print("\nAPI key configured:", bool(FLICKR_API_KEY))
+                "width":
+                    0,
 
-    diagnostic = diagnose_flickr_url(
-        TEST_URL
-    )
+                "height":
+                    0,
 
-    print("\nURL diagnostic:")
+                "source":
+                    "HTML",
 
-    for key, value in diagnostic.items():
-        print(f"  {key}: {value}")
+                "license":
+                    "",
 
-    if FLICKR_API_KEY:
+                "date_taken":
+                    "",
 
-        print("\nRetrieving Flickr metadata...")
+                "date_uploaded":
+                    "",
 
-        try:
+                "views":
+                    "",
 
-            records = get_flickr_images(
-                TEST_URL,
-                max_images=1
-            )
-
-            if records:
-
-                record = records[0]
-
-                print("\nRESULT")
-                print("-" * 70)
-
-                important_fields = [
-                    "flickr_photo_id",
-                    "flickr_owner_name",
-                    "title",
-                    "publication_date",
-                    "publication_date_source",
-                    "flickr_date_upload",
-                    "flickr_date_taken",
-                    "flickr_date_taken_granularity",
-                    "flickr_last_update",
-                    "width",
-                    "height",
-                    "views",
-                    "url",
-                    "page_url",
-                ]
+                "tags":
+                    "",
 
-                for field in important_fields:
+                "description":
+                    "",
 
-                    print(
-                        f"{field}: "
-                        f"{record.get(field)}"
-                    )
+                "alt":
+                    alt,
 
-            else:
+            }
+        )
+
+    return resolved
+
+
+def generic_page_images(
+    page_url,
+    max_images=50,
+):
+
+    response = session.get(
+        page_url,
+        timeout=REQUEST_TIMEOUT,
+        allow_redirects=True,
+    )
+
+    response.raise_for_status()
+
+    content_type = (
+        response.headers
+        .get(
+            "Content-Type",
+            ""
+        )
+        .lower()
+    )
+
+    if (
+        "html" not in content_type
+        and "xhtml" not in content_type
+    ):
+
+        if content_type.startswith(
+            "image/"
+        ):
+
+            return [
+
+                {
+
+                    "image_url":
+                        response.url,
+
+                    "page_url":
+                        page_url,
+
+                    "title":
+                        "",
+
+                    "owner":
+                        "",
+
+                    "photo_id":
+                        "",
+
+                    "width":
+                        0,
+
+                    "height":
+                        0,
+
+                    "source":
+                        "Direct image",
+
+                    "license":
+                        "",
+
+                    "date_taken":
+                        "",
+
+                    "date_uploaded":
+                        "",
+
+                    "views":
+                        "",
+
+                    "tags":
+                        "",
+
+                    "description":
+                        "",
+
+                    "alt":
+                        "",
+
+                }
+
+            ]
+
+        raise RuntimeError(
+            "The page did not return HTML. "
+            f"Content-Type: {content_type}"
+        )
+
+    candidates = (
+        extract_image_candidates_from_html(
+            response.url,
+            response.text,
+        )
+    )
+
+    seen = set()
+
+    unique = []
+
+    for item in candidates:
+
+        image_url = item[
+            "image_url"
+        ]
+
+        normalized = (
+            image_url
+            .split("#")[0]
+        )
+
+        if normalized in seen:
+            continue
+
+        seen.add(
+            normalized
+        )
+
+        unique.append(
+            item
+        )
+
+        if len(unique) >= max_images:
+            break
+
+    return unique
+
+
+# ============================================================
+# DOWNLOAD + METADATA
+# ============================================================
+
+def download_image(
+    item,
+    output_dir,
+    index,
+    min_width=0,
+    min_height=0,
+):
+
+    image_url = item[
+        "image_url"
+    ]
+
+    try:
+
+        response = session.get(
+            image_url,
+            timeout=IMAGE_TIMEOUT,
+            stream=True,
+            allow_redirects=True,
+        )
+
+        response.raise_for_status()
+
+        content_type = (
+            response.headers
+            .get(
+                "Content-Type",
+                ""
+            )
+            .lower()
+        )
+
+        if (
+            content_type
+            and not content_type.startswith(
+                "image/"
+            )
+        ):
 
-                print(
-                    "No Flickr record returned."
+            if (
+                "octet-stream"
+                not in content_type
+            ):
+
+                return (
+                    None,
+                    f"Not an image: "
+                    f"{content_type}"
                 )
 
+        data = response.content
+
+        if not data:
+
+            return (
+                None,
+                "Empty response"
+            )
+
+        # ----------------------------------------------------
+        # PIL
+        # ----------------------------------------------------
+
+        try:
+
+            image = Image.open(
+                io.BytesIO(data)
+            )
+
+            width, height = (
+                image.size
+            )
+
+            image_format = (
+                image.format
+                or "JPEG"
+            ).lower()
+
         except Exception as exc:
 
-            print(
-                "\nERROR:",
-                exc
+            return (
+                None,
+                f"Invalid image: {exc}"
             )
 
-    else:
+        # ----------------------------------------------------
+        # Dimension filtering
+        # ----------------------------------------------------
+
+        if (
+            min_width
+            and width < min_width
+        ):
+
+            return (
+                None,
+                f"Too narrow: "
+                f"{width}px"
+            )
+
+        if (
+            min_height
+            and height < min_height
+        ):
+
+            return (
+                None,
+                f"Too short: "
+                f"{height}px"
+            )
+
+        # ----------------------------------------------------
+        # EXIF
+        # ----------------------------------------------------
+
+        exif_metadata = (
+            extract_exif_metadata(
+                image
+            )
+        )
+
+        # ----------------------------------------------------
+        # Extension
+        # ----------------------------------------------------
+
+        extension_map = {
+
+            "jpeg": ".jpg",
+            "jpg": ".jpg",
+            "png": ".png",
+            "webp": ".webp",
+            "gif": ".gif",
+            "bmp": ".bmp",
+            "tiff": ".tif",
+            "avif": ".avif",
+
+        }
+
+        extension = (
+            extension_map.get(
+                image_format,
+                extension_from_content_type(
+                    content_type
+                )
+            )
+        )
+
+        # ----------------------------------------------------
+        # Filename
+        # ----------------------------------------------------
+
+        original_name = ""
+
+        try:
+
+            original_name = Path(
+                urlparse(
+                    image_url
+                ).path
+            ).name
+
+        except Exception:
+            pass
+
+        if original_name:
+
+            original_stem = Path(
+                original_name
+            ).stem
+
+            original_stem = (
+                safe_filename(
+                    original_stem,
+                    f"image_{index:05d}"
+                )
+            )
+
+        else:
+
+            original_stem = (
+                f"image_{index:05d}"
+            )
+
+        filename = (
+            f"{index:05d}_"
+            f"{original_stem}"
+            f"{extension}"
+        )
+
+        filename = safe_filename(
+            filename,
+            f"image_{index:05d}"
+            f"{extension}"
+        )
+
+        output_path = (
+            Path(output_dir)
+            / filename
+        )
+
+        with open(
+            output_path,
+            "wb"
+        ) as f:
+
+            f.write(data)
+
+        # ----------------------------------------------------
+        # Dates
+        # ----------------------------------------------------
+
+        flickr_date_taken = (
+            item.get(
+                "date_taken",
+                ""
+            )
+        )
+
+        flickr_date_uploaded = (
+            item.get(
+                "date_uploaded",
+                ""
+            )
+        )
+
+        exif_original = (
+            exif_metadata.get(
+                "exif_datetime_original",
+                ""
+            )
+        )
+
+        exif_datetime = (
+            exif_metadata.get(
+                "exif_datetime",
+                ""
+            )
+        )
+
+        # Best available date
+
+        if flickr_date_taken:
+
+            date_used = (
+                flickr_date_taken
+            )
+
+            date_source = (
+                "Flickr date taken"
+            )
+
+        elif exif_original:
+
+            date_used = (
+                exif_original
+            )
+
+            date_source = (
+                "EXIF DateTimeOriginal"
+            )
+
+        elif exif_datetime:
+
+            date_used = (
+                exif_datetime
+            )
+
+            date_source = (
+                "EXIF DateTime"
+            )
+
+        elif flickr_date_uploaded:
+
+            date_used = (
+                flickr_date_uploaded
+            )
+
+            date_source = (
+                "Flickr upload date"
+            )
+
+        else:
+
+            date_used = ""
+            date_source = ""
+
+        parsed_date = parse_date(
+            date_used
+        )
+
+        # ----------------------------------------------------
+        # Aspect ratio
+        # ----------------------------------------------------
+
+        if height:
+
+            aspect_ratio = round(
+                width / height,
+                3
+            )
+
+        else:
+
+            aspect_ratio = ""
+
+        # ----------------------------------------------------
+        # File hash
+        # ----------------------------------------------------
+
+        file_sha256 = hashlib.sha256(
+            data
+        ).hexdigest()
+
+        # ----------------------------------------------------
+        # Build record
+        # ----------------------------------------------------
+
+        record = dict(
+            item
+        )
+
+        record.update(
+            {
+
+                "filename":
+                    filename,
+
+                "local_file":
+                    str(output_path),
+
+                "final_url":
+                    response.url,
+
+                "width":
+                    width,
+
+                "height":
+                    height,
+
+                "aspect_ratio":
+                    aspect_ratio,
+
+                "format":
+                    image_format,
+
+                "file_size_bytes":
+                    len(data),
+
+                "file_size_mb":
+                    round(
+                        len(data)
+                        / 1024
+                        / 1024,
+                        3
+                    ),
+
+                "sha256":
+                    file_sha256,
+
+                "date_used":
+                    date_used,
+
+                "date_source":
+                    date_source,
+
+                "date_parsed":
+                    (
+                        parsed_date.strftime(
+                            "%Y-%m-%d"
+                        )
+                        if not pd.isna(
+                            parsed_date
+                        )
+                        else ""
+                    ),
+
+                "week":
+                    (
+                        parsed_date.strftime(
+                            "%Y-W%V"
+                        )
+                        if not pd.isna(
+                            parsed_date
+                        )
+                        else ""
+                    ),
+
+                "download_status":
+                    "OK",
+
+            }
+        )
+
+        record.update(
+            exif_metadata
+        )
+
+        return (
+            record,
+            None
+        )
+
+    except Exception as exc:
+
+        return (
+            None,
+            str(exc)
+        )
+
+
+# ============================================================
+# DATAFRAME CREATION
+# ============================================================
+
+def records_to_dataframe(
+    records
+):
+
+    if not records:
+
+        return pd.DataFrame()
+
+    df = pd.DataFrame(
+        records
+    )
+
+    preferred_columns = [
+
+        "filename",
+
+        "title",
+        "owner",
+        "photo_id",
+
+        "source",
+
+        "page_url",
+        "image_url",
+        "final_url",
+
+        "date_used",
+        "date_source",
+        "date_parsed",
+        "week",
+
+        "date_taken",
+        "date_uploaded",
+
+        "width",
+        "height",
+        "aspect_ratio",
+
+        "format",
+
+        "file_size_bytes",
+        "file_size_mb",
+
+        "license",
+        "tags",
+        "description",
+        "views",
+        "alt",
+
+        "exif_make",
+        "exif_model",
+        "exif_software",
+
+        "exif_datetime",
+        "exif_datetime_original",
+        "exif_datetime_digitized",
+
+        "exif_orientation",
+        "exif_lens_model",
+        "exif_focal_length",
+        "exif_iso",
+        "exif_exposure_time",
+        "exif_f_number",
+
+        "exif_gps_latitude",
+        "exif_gps_longitude",
+        "exif_gps_altitude",
+
+        "sha256",
+
+        "download_status",
+
+    ]
+
+    existing = [
+        col
+        for col in preferred_columns
+        if col in df.columns
+    ]
+
+    remaining = [
+        col
+        for col in df.columns
+        if col not in existing
+        and col != "local_file"
+    ]
+
+    df = df[
+        existing + remaining
+    ]
+
+    return df
+
+
+# ============================================================
+# WEEKLY DATA
+# ============================================================
+
+def create_weekly_dataframe(
+    df
+):
+
+    if df.empty:
+
+        return pd.DataFrame(
+            columns=[
+                "week",
+                "week_start",
+                "number_of_pictures",
+            ]
+        )
+
+    temp = df.copy()
+
+    temp[
+        "_date"
+    ] = pd.to_datetime(
+        temp["date_parsed"],
+        errors="coerce"
+    )
+
+    temp = temp[
+        temp["_date"].notna()
+    ].copy()
+
+    if temp.empty:
+
+        return pd.DataFrame(
+            columns=[
+                "week",
+                "week_start",
+                "number_of_pictures",
+            ]
+        )
+
+    # Monday-based week
+
+    temp[
+        "week_start"
+    ] = (
+        temp["_date"]
+        - pd.to_timedelta(
+            temp["_date"].dt.weekday,
+            unit="D"
+        )
+    ).dt.normalize()
+
+    weekly = (
+        temp
+        .groupby(
+            "week_start"
+        )
+        .size()
+        .reset_index(
+            name="number_of_pictures"
+        )
+    )
+
+    weekly[
+        "week"
+    ] = weekly[
+        "week_start"
+    ].dt.strftime(
+        "%Y-W%V"
+    )
+
+    weekly = weekly[
+        [
+            "week",
+            "week_start",
+            "number_of_pictures",
+        ]
+    ]
+
+    weekly = weekly.sort_values(
+        "week_start"
+    )
+
+    return weekly
+
+
+# ============================================================
+# WEEKLY PLOT
+# ============================================================
+
+def create_weekly_plot(
+    weekly_df,
+    output_path
+):
+
+    if weekly_df.empty:
+
+        return None
+
+    plt.figure(
+        figsize=(12, 6)
+    )
+
+    x = np.arange(
+        len(weekly_df)
+    )
+
+    y = (
+        weekly_df[
+            "number_of_pictures"
+        ]
+        .astype(int)
+        .values
+    )
+
+    plt.bar(
+        x,
+        y
+    )
+
+    labels = (
+        weekly_df[
+            "week"
+        ]
+        .tolist()
+    )
+
+    # Avoid unreadable labels
+    # when there are many weeks.
+
+    if len(labels) > 30:
+
+        step = math.ceil(
+            len(labels) / 30
+        )
+
+        shown_labels = [
+            label if i % step == 0
+            else ""
+            for i, label
+            in enumerate(labels)
+        ]
+
+    else:
+
+        shown_labels = labels
+
+    plt.xticks(
+        x,
+        shown_labels,
+        rotation=45,
+        ha="right"
+    )
+
+    plt.xlabel(
+        "Week"
+    )
+
+    plt.ylabel(
+        "Number of pictures"
+    )
+
+    plt.title(
+        "Number of pictures per week"
+    )
+
+    plt.grid(
+        axis="y",
+        alpha=0.25
+    )
+
+    plt.tight_layout()
+
+    plt.savefig(
+        output_path,
+        dpi=180,
+        bbox_inches="tight"
+    )
+
+    plt.close()
+
+    return str(
+        output_path
+    )
+
+
+# ============================================================
+# XLSX EXPORT
+# ============================================================
+
+def create_xlsx(
+    df,
+    weekly_df,
+    output_path
+):
+
+    summary_rows = [
+
+        {
+            "metric":
+                "Number of pictures",
+            "value":
+                len(df),
+        },
+
+        {
+            "metric":
+                "Pictures with date",
+            "value":
+                int(
+                    df[
+                        "date_parsed"
+                    ]
+                    .notna()
+                    .sum()
+                )
+                if (
+                    not df.empty
+                    and "date_parsed"
+                    in df.columns
+                )
+                else 0,
+        },
+
+        {
+            "metric":
+                "Pictures with EXIF",
+            "value":
+                int(
+                    (
+                        df[
+                            "exif_model"
+                        ]
+                        .fillna("")
+                        .astype(str)
+                        .str.len()
+                        > 0
+                    ).sum()
+                )
+                if (
+                    not df.empty
+                    and "exif_model"
+                    in df.columns
+                )
+                else 0,
+        },
+
+        {
+            "metric":
+                "Pictures with GPS",
+            "value":
+                int(
+                    (
+                        df[
+                            "exif_gps_latitude"
+                        ]
+                        .astype(str)
+                        .str.len()
+                        > 0
+                    ).sum()
+                )
+                if (
+                    not df.empty
+                    and "exif_gps_latitude"
+                    in df.columns
+                )
+                else 0,
+        },
+
+    ]
+
+    summary_df = pd.DataFrame(
+        summary_rows
+    )
+
+    with pd.ExcelWriter(
+        output_path,
+        engine="openpyxl"
+    ) as writer:
+
+        df.to_excel(
+            writer,
+            sheet_name="Metadata",
+            index=False
+        )
+
+        weekly_df.to_excel(
+            writer,
+            sheet_name="Weekly_counts",
+            index=False
+        )
+
+        summary_df.to_excel(
+            writer,
+            sheet_name="Summary",
+            index=False
+        )
+
+        # ----------------------------------------------------
+        # Formatting
+        # ----------------------------------------------------
+
+        workbook = writer.book
+
+        for sheet_name in [
+            "Metadata",
+            "Weekly_counts",
+            "Summary",
+        ]:
+
+            worksheet = workbook[
+                sheet_name
+            ]
+
+            worksheet.freeze_panes = "A2"
+
+            # Auto width, capped
+            for column_cells in (
+                worksheet.columns
+            ):
+
+                max_length = 0
+
+                column_letter = (
+                    column_cells[0]
+                    .column_letter
+                )
+
+                for cell in column_cells:
+
+                    try:
+
+                        value_length = len(
+                            str(
+                                cell.value
+                            )
+                        )
+
+                        max_length = max(
+                            max_length,
+                            value_length
+                        )
+
+                    except Exception:
+                        pass
+
+                worksheet.column_dimensions[
+                    column_letter
+                ].width = min(
+                    max(
+                        max_length + 2,
+                        10
+                    ),
+                    45
+                )
+
+
+# ============================================================
+# ZIP CREATION
+# ============================================================
+
+def build_zip(
+    records,
+    zip_path,
+    csv_path,
+    xlsx_path,
+    plot_path=None
+):
+
+    with zipfile.ZipFile(
+        zip_path,
+        "w",
+        compression=zipfile.ZIP_DEFLATED
+    ) as z:
+
+        for record in records:
+
+            local_file = record.get(
+                "local_file"
+            )
+
+            if not local_file:
+                continue
+
+            if not os.path.exists(
+                local_file
+            ):
+                continue
+
+            filename = record.get(
+                "filename",
+                Path(
+                    local_file
+                ).name
+            )
+
+            z.write(
+                local_file,
+                arcname=(
+                    f"images/{filename}"
+                )
+            )
+
+        if os.path.exists(
+            csv_path
+        ):
+
+            z.write(
+                csv_path,
+                arcname="metadata.csv"
+            )
+
+        if os.path.exists(
+            xlsx_path
+        ):
+
+            z.write(
+                xlsx_path,
+                arcname="metadata.xlsx"
+            )
+
+        if (
+            plot_path
+            and os.path.exists(
+                plot_path
+            )
+        ):
+
+            z.write(
+                plot_path,
+                arcname=(
+                    "weekly_picture_count.png"
+                )
+            )
+
+
+# ============================================================
+# MAIN FUNCTION
+# ============================================================
+
+def find_images(
+    url,
+    max_images,
+    min_width,
+    min_height,
+    remove_duplicates,
+):
+
+    url = clean_url(
+        url
+    )
+
+    if not url:
+
+        return (
+            [],
+            "❌ Please enter a URL.",
+            [],
+            pd.DataFrame(),
+            None,
+            None,
+            None,
+            ""
+        )
+
+    if not valid_http_url(
+        url
+    ):
+
+        return (
+            [],
+            "❌ Invalid HTTP/HTTPS URL.",
+            [],
+            pd.DataFrame(),
+            None,
+            None,
+            None,
+            ""
+        )
+
+    max_images = min(
+        int(max_images),
+        MAX_IMAGES_HARD_LIMIT
+    )
+
+    min_width = int(
+        min_width or 0
+    )
+
+    min_height = int(
+        min_height or 0
+    )
+
+    # --------------------------------------------------------
+    # Job directory
+    # --------------------------------------------------------
+
+    job_id = (
+        f"{int(time.time())}_"
+        f"{make_hash(url)}"
+    )
+
+    job_dir = (
+        BASE_DIR
+        / job_id
+    )
+
+    job_dir.mkdir(
+        parents=True,
+        exist_ok=True
+    )
+
+    # --------------------------------------------------------
+    # Find candidates
+    # --------------------------------------------------------
+
+    try:
+
+        if is_flickr_url(
+            url
+        ):
+
+            search_text = (
+                extract_flickr_search_text(
+                    url
+                )
+            )
+
+            if (
+                FLICKR_API_KEY
+                and search_text
+            ):
+
+                mode_message = (
+                    "Flickr API mode"
+                )
+
+                candidates = flickr_search(
+                    search_text,
+                    max_images=max_images,
+                    min_width=min_width,
+                    min_height=min_height,
+                )
+
+            else:
+
+                mode_message = (
+                    "HTML webpage mode"
+                )
+
+                candidates = (
+                    generic_page_images(
+                        url,
+                        max_images=max_images,
+                    )
+                )
+
+        else:
+
+            mode_message = (
+                "Generic webpage mode"
+            )
+
+            candidates = (
+                generic_page_images(
+                    url,
+                    max_images=max_images,
+                )
+            )
+
+    except Exception as exc:
+
+        return (
+            [],
+            (
+                "❌ Could not retrieve the page.\n\n"
+                f"{type(exc).__name__}: {exc}"
+            ),
+            [],
+            pd.DataFrame(),
+            None,
+            None,
+            None,
+            ""
+        )
+
+    if not candidates:
+
+        return (
+            [],
+            "⚠️ No image candidates were found.",
+            [],
+            pd.DataFrame(),
+            None,
+            None,
+            None,
+            ""
+        )
+
+    # --------------------------------------------------------
+    # URL deduplication
+    # --------------------------------------------------------
+
+    if remove_duplicates:
+
+        seen = set()
+
+        unique = []
+
+        for item in candidates:
+
+            image_url = item.get(
+                "image_url",
+                ""
+            )
+
+            normalized = (
+                image_url
+                .split("#")[0]
+            )
+
+            if normalized in seen:
+                continue
+
+            seen.add(
+                normalized
+            )
+
+            unique.append(
+                item
+            )
+
+        candidates = unique
+
+    # --------------------------------------------------------
+    # Download
+    # --------------------------------------------------------
+
+    downloaded = []
+
+    errors = []
+
+    for index, item in enumerate(
+        candidates,
+        start=1
+    ):
+
+        result, error = (
+            download_image(
+                item,
+                job_dir,
+                index,
+                min_width=min_width,
+                min_height=min_height,
+            )
+        )
+
+        if result:
+
+            downloaded.append(
+                result
+            )
+
+        else:
+
+            errors.append(
+                {
+                    "url":
+                        item.get(
+                            "image_url",
+                            ""
+                        ),
+                    "error":
+                        error,
+                }
+            )
+
+        if len(downloaded) >= max_images:
+            break
+
+    # --------------------------------------------------------
+    # Exact duplicate detection
+    # --------------------------------------------------------
+
+    if remove_duplicates and downloaded:
+
+        seen_hashes = set()
+
+        unique_downloaded = []
+
+        duplicate_records = []
+
+        for record in downloaded:
+
+            file_hash = record.get(
+                "sha256"
+            )
+
+            if file_hash in seen_hashes:
+
+                duplicate_records.append(
+                    record
+                )
+
+                try:
+
+                    os.remove(
+                        record[
+                            "local_file"
+                        ]
+                    )
+
+                except Exception:
+                    pass
+
+                continue
+
+            seen_hashes.add(
+                file_hash
+            )
+
+            unique_downloaded.append(
+                record
+            )
+
+        downloaded = (
+            unique_downloaded
+        )
+
+    # --------------------------------------------------------
+    # DataFrame
+    # --------------------------------------------------------
+
+    df = records_to_dataframe(
+        downloaded
+    )
+
+    weekly_df = create_weekly_dataframe(
+        df
+    )
+
+    # --------------------------------------------------------
+    # Files
+    # --------------------------------------------------------
+
+    csv_path = (
+        job_dir
+        / "metadata.csv"
+    )
+
+    xlsx_path = (
+        job_dir
+        / "metadata.xlsx"
+    )
+
+    plot_path = (
+        job_dir
+        / "weekly_picture_count.png"
+    )
+
+    df.to_csv(
+        csv_path,
+        index=False,
+        encoding="utf-8-sig"
+    )
+
+    create_xlsx(
+        df,
+        weekly_df,
+        xlsx_path
+    )
+
+    create_weekly_plot(
+        weekly_df,
+        plot_path
+    )
+
+    # --------------------------------------------------------
+    # Gallery
+    # --------------------------------------------------------
+
+    gallery = []
+
+    for record in downloaded:
+
+        local_file = record.get(
+            "local_file"
+        )
+
+        if not local_file:
+            continue
+
+        caption = (
+            record.get(
+                "title"
+            )
+            or record.get(
+                "filename"
+            )
+        )
+
+        gallery.append(
+            (
+                local_file,
+                caption
+            )
+        )
+
+    # --------------------------------------------------------
+    # Status
+    # --------------------------------------------------------
+
+    dated_count = 0
+
+    if not df.empty:
+
+        dated_count = int(
+            df[
+                "date_parsed"
+            ]
+            .fillna("")
+            .astype(str)
+            .str.len()
+            .gt(0)
+            .sum()
+        )
+
+    exif_count = 0
+
+    if not df.empty:
+
+        exif_count = int(
+            df[
+                "exif_model"
+            ]
+            .fillna("")
+            .astype(str)
+            .str.len()
+            .gt(0)
+            .sum()
+        )
+
+    gps_count = 0
+
+    if not df.empty:
+
+        gps_count = int(
+            df[
+                "exif_gps_latitude"
+            ]
+            .fillna("")
+            .astype(str)
+            .str.len()
+            .gt(0)
+            .sum()
+        )
+
+    status_lines = [
+
+        f"### {mode_message}",
+
+        "",
+
+        f"**Candidates found:** "
+        f"{len(candidates)}",
+
+        f"**Images downloaded:** "
+        f"{len(downloaded)}",
+
+        f"**Failed downloads:** "
+        f"{len(errors)}",
+
+        "",
+
+        f"**Images with usable date:** "
+        f"{dated_count}",
+
+        f"**Images with camera EXIF:** "
+        f"{exif_count}",
+
+        f"**Images with GPS EXIF:** "
+        f"{gps_count}",
+
+        "",
+
+        f"**Weeks represented:** "
+        f"{len(weekly_df)}",
+
+        "",
+
+        "Metadata XLSX and weekly plot "
+        "are ready.",
+
+    ]
+
+    if errors:
+
+        status_lines.extend(
+            [
+                "",
+                "### Download errors",
+            ]
+        )
+
+        for error in errors[:10]:
+
+            status_lines.append(
+                f"- {error['error']}"
+            )
+
+    status = "\n".join(
+        status_lines
+    )
+
+    return (
+        gallery,
+        status,
+        downloaded,
+        df,
+        weekly_df,
+        str(plot_path)
+        if os.path.exists(
+            plot_path
+        )
+        else None,
+        str(xlsx_path),
+        str(csv_path),
+    )
+
+
+# ============================================================
+# ZIP CREATION
+# ============================================================
+
+def create_zip(
+    items,
+    xlsx_path,
+    csv_path,
+    plot_path,
+):
+
+    if not items:
+
+        return (
+            None,
+            "❌ There are no downloaded images."
+        )
+
+    try:
+
+        first_file = Path(
+            items[0]["local_file"]
+        )
+
+        job_dir = (
+            first_file.parent
+        )
+
+        timestamp = time.strftime(
+            "%Y%m%d_%H%M%S"
+        )
+
+        zip_path = (
+            job_dir.parent
+            / f"images_{timestamp}.zip"
+        )
+
+        build_zip(
+            items,
+            zip_path,
+            csv_path,
+            xlsx_path,
+            plot_path,
+        )
+
+        total_size = (
+            zip_path.stat().st_size
+        )
+
+        size_mb = (
+            total_size
+            / 1024
+            / 1024
+        )
+
+        return (
+            str(zip_path),
+            (
+                "### ✅ ZIP created\n\n"
+                f"Images: {len(items)}\n\n"
+                f"ZIP size: {size_mb:.2f} MB\n\n"
+                "Contents:\n"
+                "- `images/`\n"
+                "- `metadata.csv`\n"
+                "- `metadata.xlsx`\n"
+                "- `weekly_picture_count.png`"
+            )
+        )
+
+    except Exception as exc:
+
+        return (
+            None,
+            f"❌ ZIP creation failed: {exc}"
+        )
+
+
+# ============================================================
+# CLEAR
+# ============================================================
+
+def clear_all():
+
+    return (
+        "",
+        [],
+        "Ready.",
+        [],
+        pd.DataFrame(),
+        None,
+        None,
+        None,
+        None,
+        "",
+    )
+
+
+# ============================================================
+# DESCRIPTION
+# ============================================================
+
+DESCRIPTION = """
+## 🖼️ Web & Flickr Image Downloader
+Download images from Flickr or ordinary webpages and automatically
+extract image metadata.
+### Flickr
+Add a Hugging Face Space Secret:
+`FLICKR_API_KEY`
+Then use for example:
+`https://www.flickr.com/search/?text=ai`
+The application uses the Flickr API when the key is available.
+### Metadata
+The application collects:
+**Flickr**
+- title
+- photographer
+- Flickr ID
+- license
+- tags
+- views
+- date taken
+- date uploaded
+- description
+**Image / EXIF**
+- width
+- height
+- aspect ratio
+- format
+- file size
+- SHA-256
+- camera manufacturer
+- camera model
+- software
+- original date/time
+- lens
+- focal length
+- ISO
+- exposure
+- aperture
+- GPS latitude/longitude/altitude
+### Date used for the weekly analysis
+The application uses the first available date in this order:
+1. Flickr date taken
+2. EXIF DateTimeOriginal
+3. EXIF DateTime
+4. Flickr upload date
+The weekly chart uses Monday as the beginning of the week.
+### Exports
+You receive:
+- metadata table
+- `metadata.csv`
+- `metadata.xlsx`
+- weekly bar chart
+- ZIP containing everything
+"""
+
+
+# ============================================================
+# GRADIO UI
+# ============================================================
+
+with gr.Blocks(
+    title=APP_TITLE
+) as demo:
+
+    gr.Markdown(
+        "# 🖼️ Web & Flickr Image Downloader"
+    )
+
+    gr.Markdown(
+        DESCRIPTION
+    )
+
+    # --------------------------------------------------------
+    # INPUT
+    # --------------------------------------------------------
+
+    with gr.Row():
+
+        with gr.Column(
+            scale=4
+        ):
+
+            url_input = gr.Textbox(
+                label="Webpage or Flickr URL",
+                placeholder=(
+                    "https://www.flickr.com/search/?text=ai"
+                ),
+                lines=2,
+            )
+
+        with gr.Column(
+            scale=1
+        ):
+
+            max_images = gr.Slider(
+                minimum=1,
+                maximum=500,
+                value=50,
+                step=1,
+                label="Maximum images",
+            )
+
+    with gr.Row():
+
+        min_width = gr.Number(
+            value=0,
+            minimum=0,
+            maximum=10000,
+            step=100,
+            label="Minimum width (px)",
+        )
+
+        min_height = gr.Number(
+            value=0,
+            minimum=0,
+            maximum=10000,
+            step=100,
+            label="Minimum height (px)",
+        )
+
+        remove_duplicates = gr.Checkbox(
+            value=True,
+            label="Remove duplicates",
+        )
+
+    with gr.Row():
+
+        find_button = gr.Button(
+            "🔎 Find & Analyze Images",
+            variant="primary",
+        )
+
+        clear_button = gr.Button(
+            "🧹 Clear",
+        )
+
+    # --------------------------------------------------------
+    # STATUS
+    # --------------------------------------------------------
+
+    status = gr.Markdown(
+        "Ready."
+    )
+
+    # --------------------------------------------------------
+    # GALLERY
+    # --------------------------------------------------------
+
+    gallery = gr.Gallery(
+        label="Downloaded images",
+        show_label=True,
+        columns=5,
+        rows=3,
+        height="auto",
+        object_fit="contain",
+        allow_preview=True,
+    )
+
+    # --------------------------------------------------------
+    # STATE
+    # --------------------------------------------------------
+
+    image_state = gr.State(
+        []
+    )
+
+    xlsx_state = gr.State(
+        None
+    )
+
+    csv_state = gr.State(
+        None
+    )
+
+    plot_state = gr.State(
+        None
+    )
+
+    # --------------------------------------------------------
+    # METADATA
+    # --------------------------------------------------------
+
+    gr.Markdown(
+        "## 📋 Image metadata"
+    )
+
+    metadata_table = gr.Dataframe(
+        headers=None,
+        value=pd.DataFrame(),
+        datatype=None,
+        interactive=False,
+        wrap=True,
+        label="Metadata",
+    )
+
+    # --------------------------------------------------------
+    # WEEKLY
+    # --------------------------------------------------------
+
+    gr.Markdown(
+        "## 📅 Pictures per week"
+    )
+
+    weekly_table = gr.Dataframe(
+        headers=None,
+        value=pd.DataFrame(),
+        datatype=None,
+        interactive=False,
+        label="Weekly counts",
+    )
+
+    weekly_plot = gr.Image(
+        label="Number of pictures per week",
+        type="filepath",
+    )
+
+    # --------------------------------------------------------
+    # DOWNLOADS
+    # --------------------------------------------------------
+
+    gr.Markdown(
+        "## 📥 Downloads"
+    )
+
+    with gr.Row():
+
+        xlsx_file = gr.File(
+            label="Excel metadata",
+        )
+
+        csv_file = gr.File(
+            label="CSV metadata",
+        )
+
+        plot_file = gr.File(
+            label="Weekly plot PNG",
+        )
+
+    # --------------------------------------------------------
+    # ZIP
+    # --------------------------------------------------------
+
+    gr.Markdown(
+        "## 📦 Complete ZIP"
+    )
+
+    with gr.Row():
+
+        zip_button = gr.Button(
+            "📦 Create Complete ZIP",
+            variant="primary",
+        )
+
+        zip_file = gr.File(
+            label="Complete ZIP",
+        )
+
+    zip_status = gr.Markdown(
+        ""
+    )
+
+    # --------------------------------------------------------
+    # EVENTS
+    # --------------------------------------------------------
+
+    find_button.click(
+        fn=find_images,
+        inputs=[
+            url_input,
+            max_images,
+            min_width,
+            min_height,
+            remove_duplicates,
+        ],
+        outputs=[
+            gallery,
+            status,
+            image_state,
+            metadata_table,
+            weekly_table,
+            weekly_plot,
+            xlsx_file,
+            csv_file,
+        ],
+    )
+
+    zip_button.click(
+        fn=create_zip,
+        inputs=[
+            image_state,
+            xlsx_state,
+            csv_state,
+            plot_state,
+        ],
+        outputs=[
+            zip_file,
+            zip_status,
+        ],
+    )
+
+    # --------------------------------------------------------
+    # IMPORTANT:
+    # State values need to be populated independently.
+    # --------------------------------------------------------
+
+    def store_export_paths(
+        xlsx_path,
+        csv_path,
+        plot_path,
+    ):
+
+        return (
+            xlsx_path,
+            csv_path,
+            plot_path,
+        )
+
+    # The output files from find_images are also stored
+    # through these hidden State components.
+
+    find_button.click(
+        fn=store_export_paths,
+        inputs=[
+            xlsx_file,
+            csv_file,
+            plot_file,
+        ],
+        outputs=[
+            xlsx_state,
+            csv_state,
+            plot_state,
+        ],
+    )
+
+    # --------------------------------------------------------
+    # CLEAR
+    # --------------------------------------------------------
+
+    clear_button.click(
+        fn=clear_all,
+        inputs=[],
+        outputs=[
+            url_input,
+            gallery,
+            status,
+            image_state,
+            metadata_table,
+            weekly_plot,
+            xlsx_file,
+            csv_file,
+            plot_file,
+            zip_file,
+        ],
+    )
+
+
+# ============================================================
+# LAUNCH
+# ============================================================
+
+if __name__ == "__main__":
 
-        print(
-            "\nSet FLICKR_API_KEY before testing."
-        )
+    demo.launch()