Skip to content

PROVIDERS.md

Latest commit

 

History

History
98 lines (91 loc) · 8.38 KB

PROVIDERS.md

File metadata and controls

98 lines (91 loc) · 8.38 KB
Raw

Provider Coverage Matrix

Provider Kinds covered Default license Auth Rate limit (conservative) Opt-in
wikimedia portraits, events, logos, history CC_BY_SA (from meta) none (UA required) 20/s no
openverse any CC-licensed content CC_BY (from meta) none 5/s no
unsplash high-quality photography UNSPLASH_LICENSE UNSPLASH_ACCESS_KEY 1/s (demo-key budget) no
pexels stock photography PEXELS_LICENSE PEXELS_API_KEY 3/s no
pixabay stock photos, illustrations PIXABAY_LICENSE PIXABAY_API_KEY 2/s no
itunes album covers, artist portraits EDITORIAL_LICENSED none 5/s no
musicbrainz-caa canonical album art EDITORIAL_LICENSED none (UA required) 1/s (hard MB limit) no
spotify artist + album images EDITORIAL_LICENSED SPOTIFY_CLIENT_ID/SECRET 10/s no
youtube-thumb video thumbnail given id/URL EDITORIAL_LICENSED none 20/s yes (narrow-source provider)
brave general web image search UNKNOWN (+heuristic) BRAVE_API_KEY 1/s no
bing general web image search UNKNOWN (+heuristic) BING_API_KEY 3/s yes (API deprecation risk)
serpapi Google Images wrapper, reverse-image UNKNOWN (+heuristic) SERPAPI_KEY 2/s yes
browser headless fallback vs images.google.com UNKNOWN (+heuristic) none (requires playwright installed) 0.25/s yes (ToS-grey)
managed-browser Bright Data managed browser fallback UNKNOWN (+heuristic) BRIGHTDATA_API_TOKEN (+ optional BRIGHTDATA_ZONE) 0.5/s yes (server/cloud fallback)
flickr CC-licensed + PD photos CC_BY (from meta) FLICKR_API_KEY (free; gracefully skips) 3/s no
internet-archive PD / CC images across IA mediatype PUBLIC_DOMAIN none 5/s no
smithsonian Open Access museum collection (all CC0) CC0 SMITHSONIAN_API_KEY (defaults DEMO_KEY) 1/s (DEMO_KEY budget) no
nasa NASA imagery archive (all public domain) PUBLIC_DOMAIN none 5/s no
met-museum The Met Open Access (CC0 PD objects) CC0 none 4/s no
europeana European cultural heritage (CC/PD) CC_BY (from meta) EUROPEANA_API_KEY (free; gracefully skips) 5/s no
library-of-congress US historical photos/film archive PUBLIC_DOMAIN none 10/s no
wellcome-collection medical/historical imagery (CC + PDM) CC_BY (from meta) none 5/s no
rawpixel CC0 slice of Rawpixel's free library CC0 none (RAWPIXEL_API_KEY optional) 3/s no
burst Shopify Burst — 100% CC0 stock photos CC0 none 3/s no
europeana-archival Europeana TEXT records (editorial) CC_BY (from meta) EUROPEANA_API_KEY (same as europeana) 5/s yes (variant of europeana)

Gotchas

  • Wikimedia: returns mixed licenses; coercion is 100% metadata-driven. We never default to "probably CC".
  • Openverse: license_type=commercial,modification is set by default so results are commercial-safe. Results without metadata are skipped.
  • Unsplash/Pexels/Pixabay licenses: technically not CC0. They are custom platform licenses, exposed as explicit platform-license tags.
  • iTunes / MusicBrainz CAA / Spotify: EDITORIAL_LICENSED means "OK as part of album/artist identification UI under platform ToS". Always display attribution.
  • Brave: returns web images with no structured license; we upgrade via heuristicLicenseFromUrl (Unsplash host → UNSPLASH_LICENSE, Commons host → CC-BY-SA pending verification, etc).
  • Bing: Microsoft retired the classic Bing Search API mid-2025. This adapter still targets v7. Callers may need to swap endpoints.
  • SerpAPI: opt-in because it's a paid relay. Most valuable for find_similar (Google reverse image search).
  • browser: only runs when WEBFETCH_ENABLE_BROWSER=1 AND "browser" is in providers. Scraping images.google.com is brittle and ToS-grey. Every result returned via this provider is flagged viaBrowserFallback: true so downstream code can refuse to ship it.
  • managed-browser: opt-in server/cloud fallback backed by Bright Data Web Unlocker. Requires BRIGHTDATA_API_TOKEN; results remain UNKNOWN with heuristic confidence and should be treated as leads unless another source verifies the license.

New public-domain / CC providers

  • Flickr (flickr): Uses flickr.photos.search with license=1,4,5,7,8,9,10 (only safe CC / PD / CC0 — excludes NC and ND). Gracefully skips with missing-auth when FLICKR_API_KEY is absent. Confidence 0.9 because Flickr's license mapping is authoritative.
  • Internet Archive (internet-archive): Queries advancedsearch.php with mediatype:image AND (licenseurl:*creativecommons* OR rights:*public domain*). License coerced from licenseurl regex. No auth.
  • Smithsonian (smithsonian): Open Access collection is 100% CC0. Falls back to DEMO_KEY when no key is configured — good for dev, will hit a 30/hr rate limit under real load. Confidence 0.95.
  • NASA (nasa): All NASA-authored imagery is public domain (US Government work). No auth, no tokens.
  • The Met (met-museum): Two-step (search → object detail); filtered to isPublicDomain: true. CC0 with confidence 0.95.
  • Europeana (europeana): REUSABILITY=open filter restricts to CC and PD. Gracefully skips when EUROPEANA_API_KEY is absent.
  • Library of Congress (library-of-congress): Huge US PD archive, no auth. rights field is coerced conservatively — "no known restrictions" and explicit PD text map to PUBLIC_DOMAIN; anything else → UNKNOWN.
  • Wellcome Collection (wellcome-collection): Medical/historical imagery. Per-item license.id drives mapping: pdm → PUBLIC_DOMAIN, cc0 → CC0, cc-by → CC_BY. cc-by-nc-nd results are dropped (not commercially safe).
  • Rawpixel (rawpixel): Query is pinned with freecc0=1 so every result is CC0 by construction. RAWPIXEL_API_KEY optional today.
  • Burst (burst): Shopify's free stock library — 100% CC0 by policy.
  • Europeana Archival (europeana-archival): Opt-in variant of europeana that targets TYPE:TEXT records (manuscripts, newspapers, book scans) and surfaces their edmPreview thumbnails. Useful for editorial / historical layouts.

Picking providers

  • Just want a safe image? Use the defaults. DEFAULT_PROVIDERS excludes every ToS-grey source.
  • Building artist pages? Use searchArtistImages(name, kind) — it picks the right sources per kind automatically.
  • Need anything at all, license be damned? providers: ["brave", "serpapi", "browser", "managed-browser"] with licensePolicy: "any". Understand the risk.