Syndicating Photos to Flickr

A script that makes Flickr match the photo tree of my old site: upload, delete, move between albums, and write the Flickr ID and stats back into the sidecars.

Article Created Updated

Reviewed by adrian on

I have been on Flickr since 2012. When I added a photo stream to my old site, I did not want two upload workflows side by side. POSSE fits: the site is the source of truth and Flickr gets a copy. So I wrote a script that reads the site's photo tree and makes Flickr match it.

The setup

  • Source: photo collections under src/content/photos/collections/, each JPG with a JSON sidecar written by a vision model.
  • Target: my Flickr account, one photoset per leaf collection.
  • Auth: Flickr OAuth 1.0a with delete permission.
  • Tracking: scripts/flickr-tracking.json, gitignored, mapping local photo IDs to Flickr IDs and photoset IDs.

What the script does

scripts/upload-to-flickr.js runs five phases on every call:

  1. Delete: a tracked photo without a local sidecar is removed from Flickr.
  2. Verify: every tracked photo is checked against the Flickr API. Photos deleted directly on Flickr are reset and queued for a new upload.
  3. Move: photos whose collection changed leave the old album and join the new one.
  4. Upload: every sidecar without a flickrId is uploaded with title, description, tags and GPS.
  5. Retry: photos that uploaded but failed the album step are added to their album.

After the upload the flickrId goes back into the sidecar:

{
  "id": "2025-10-06-121017",
  "flickrId": "55158155787",
  "title": ["Golden Temple Bell in Sunlit Foliage", ...],
  ...
}

The sidecar holds both the local metadata and the Flickr reference. No separate platforms.json.

The tracking file

{
  "2025-10-06-121017": {
    "flickrId": "55158155787",
    "photosetId": "72177720324172664",
    "collectionSlug": "travels/asia/chiang-mai",
    "uploadedAt": "2026-03-21T10:00:00.000Z"
  }
}

It is machine state, not content, so it stays out of Git. The collectionSlug makes move detection possible: when the photo's current path no longer matches it, the script changes the album on Flickr.

Metadata from the sidecars

Flickr tags are one flat string. I wanted them to carry the photo's own tags from the vision model and the collection it sits in. The tags come from three places: the photo's tags, the camera model and the parts of the collection path.

const tags = [
  ...sidecar.tags,
  sidecar.exif.camera.toLowerCase().replace(/\s+/g, "-"),
  ...collectionSlug.split("/"),
]
  .map((t) => (t.includes(" ") ? `"${t}"` : t))
  .join(" ");

A Singapore photo tagged ["cityscape", "rain"] and taken with an iPhone 13 Pro Max gets cityscape rain iphone-13-pro-max travels asia singapore.

The sidecar stores GPS as a DMS string. The script turns it into decimal degrees for flickr.photos.geo.setLocation:

// "18 deg 48' 16.92" N, 98 deg 55' 18.92" E" → { lat: "18.804700", lon: "98.921922" }
function parseDMS(location) {
  const pattern =
    /(\d+)\s*deg\s*(\d+)'\s*([\d.]+)"\s*([NS]),\s*(\d+)\s*deg\s*(\d+)'\s*([\d.]+)"\s*([EW])/i;
  const m = location.match(pattern);
  const lat = (Number(m[1]) + Number(m[2]) / 60 + Number(m[3]) / 3600)
    * (m[4].toUpperCase() === "S" ? -1 : 1);
  const lon = (Number(m[5]) + Number(m[6]) / 60 + Number(m[7]) / 3600)
    * (m[8].toUpperCase() === "W" ? -1 : 1);
  return { lat: lat.toFixed(6), lon: lon.toFixed(6) };
}

Photosets from collections

The album title comes from the index.md frontmatter of each collection:

function readCollectionTitle(slug) {
  const mdPath = path.join("src/content/photos/collections", slug, "index.md");
  const content = fs.readFileSync(mdPath, "utf8");
  const m = content.match(/^title:\s*(.+)$/m);
  return m ? m[1].trim() : slug.split("/").at(-1);
}

If a photoset with that title exists on Flickr, the photo joins it; otherwise the script creates one. Flickr photosets cannot be nested, so the leaf name is used: travels/asia/chiang-mai becomes "Chiang Mai".

Deleting what the site deleted

Flickr has no hook that fires when I delete a local file. The tracking file knows every uploaded photo, so each run compares its keys with the local sidecars. An ID in the tracking file without a local file was deleted from the site:

const localIds = new Set(sidecarPaths.map((p) => path.basename(p, ".json")));
const deletedIds = Object.keys(tracking).filter((id) => !localIds.has(id));

for (const id of deletedIds) {
  await flickr("flickr.photos.delete", { photo_id: tracking[id].flickrId });
  delete tracking[id];
  saveTracking(tracking);
}

Deleting a file locally removes the photo from Flickr on the next run, with no extra command.

Detecting moves

When a photo moves to another collection, its stored collectionSlug no longer matches its path. The script removes it from the old photoset and adds it to the new one:

const movedPhotos = sidecarPaths.filter((p) => {
  const entry = tracking[path.basename(p, ".json")];
  return entry?.collectionSlug && entry.collectionSlug !== collectionSlugFromPath(p);
});

Stats back into the sidecars

A second script, scripts/update-flickr.js, fetches views, faves and comment counts for all public photos and writes them into the sidecars:

sidecar.flickr = { views, faves, comments };
fs.writeFileSync(sidecarPath, JSON.stringify(sidecar, null, 2), "utf8");

The stats are then available at build time. The photo detail page shows them next to the Flickr link whenever a flickrId exists:

{sidecar.flickrId && (
  <a href={`https://www.flickr.com/photos/${FLICKR_USER_ID}/${sidecar.flickrId}/`}>
    View on Flickr
    {sidecar.flickr && (
      <span>
        {sidecar.flickr.views} views · {sidecar.flickr.faves} faves · {sidecar.flickr.comments} comments
      </span>
    )}
  </a>
)}

OAuth in the terminal

Full sync needs OAuth 1.0a with delete permission. The existing OAuth tools had trouble with browser detection, so I wrote a small scripts/flickr-auth.js. It gets a request token, prints the authorisation URL, takes the PIN I type in and prints the access token, ready for .env.local.

The workflow

pnpm flickr:dry-run   # preview what would be uploaded or deleted
pnpm flickr:upload    # sync: delete removed, verify, move, upload new
pnpm flickr:update    # pull stats back into sidecars

Takeaways

  • Write the external ID into the same sidecar that holds the local metadata. One source of truth per photo.
  • One collectionSlug field in the tracking record is enough for move detection. No diffing, no history.
  • Flickr photosets are flat. Use the leaf name for the album and put the hierarchy into tags.

Based on

  • Syndicating Photos to Flickr with POSSE (raw/2026/2026-03-21/syndicating-photos-to-flickr-with-posse.md) [post]

More on this

Topic

  • IndieWeb Publishing on your own domain first and connecting personal websites with open standards such as Webmention and Microformats.

Uses

  • Astro Tool for building websites from content such as Markdown. Ships plain HTML by default and only loads JavaScript where it is needed.

Mentioned

  • Building the Photo Stream The photo stream of my old Astro site: JSON sidecars next to each JPG, import.meta.glob, a justified grid and batches revealed on scroll.
  • Photo Sidecars with a Vision Model The script vision.ts of my old site: EXIF data and a vision model's alt text, titles and tags in a JSON file next to each photo, generated locally before the deploy.

Show in the graph view