whitetirocket

Posted on May 13

I open-sourced passport photo specs for 100 countries (MIT, JSON, public API)

#api #webdev #javascript #opensource

I open-sourced passport photo specs for 100 countries (MIT, JSON, public API)

If you have ever built anything that touches passport or visa photos, you know the boring part is not the face detection or the background segmentation. It is the country specifications. Every country has slightly different size. Different background color. Different file size cap on the upload portal. A different head-height ratio. The documentation is scattered across consulate websites in 12 languages, half of which 404 every six months.

I have been maintaining this dataset for a year while building IDPhotoSnap, a free browser-only passport photo tool. Last week I published the whole thing as an open repository at github.com/whitetirocket/passport-photo-specs.

MIT licensed. JSON, TypeScript, and Python bindings. 100 countries. 248 document formats. Public HTTP API at idphotosnap.com/api/specs with no auth and CORS open.

This post is for the next person building anything in this category - you can skip the country-spec research entirely and focus on the actual product.

What is in it

Each country entry has documents (passport, visa, ID card, driving licence, residence permit). Each document has:

interface DocumentSpec {
  id: string             // 'italy-visa'
  name: string           // 'Visa'
  slug: string           // 'italy-visa-photo'
  widthMm: number        // 35
  heightMm: number       // 45
  widthPx: number        // 413 (at given DPI)
  heightPx: number       // 531
  dpi: number            // 300
  background: string     // 'Plain light grey'
  bgColor: string        // '#eeeeee' (hex)
  bgColorLabel: string   // 'Light grey'
  requirements: string[] // ['Plain light grey background', ...]
}

interface CountrySpec {
  id: string
  name: string
  flag: string
  documents: DocumentSpec[]
}

Three ways to use it

1. HTTP API (no clone)

# Full dataset (Schema.org Dataset JSON-LD wrapped)
curl https://idphotosnap.com/api/specs

# Filter to one country
curl "https://idphotosnap.com/api/specs?country=china&format=raw"

# Plain JSON (no JSON-LD wrapper)
curl https://idphotosnap.com/api/specs?format=raw

No auth. CORS open. Edge-cached 1 hour. Use in production without permission.

2. NPM-style import

// npm install github:whitetirocket/passport-photo-specs
import { findDocument, findCountry } from 'passport-photo-specs'

const chinaVisa = findDocument('china-visa-photo')
// { widthMm: 33, heightMm: 48, ... }

const india = findCountry('india')
// All India docs: passport, visa, OCI, PAN card, PCC, driving licence, voter ID

3. Plain JSON in any language

The complete dataset is at specs/specs.json (174 KB). Examples for Python, Go, and Rust are in examples/ - they show the three most common patterns: filter to one country, lookup by slug, validate spec consistency.

Why I bothered

Most passport photo tools claim "200+ countries supported" or "900+ document types". When you check what that means, two patterns appear:

They have one default spec (35x45mm, white background, ICAO 9303) and apply it as a fallback for every country that has not been independently validated. So "200 countries" is really "30 verified plus 170 ICAO defaults".
They scrape specs from each other rather than from the original government source. When a country updates its requirements (which happens every few years), the change takes 6-12 months to propagate.

For a real passport application this matters. A wrong photo gets rejected at the consulate, application delayed by days or weeks. The user paid $15 for the photo at a drugstore plus $200 for the visa, and the photo is the part that fails.

I wanted a single source of truth I could verify against government documentation directly.

Notable specs that catch tool builders

If you are building something in this category, these formats are commonly mis-specified across the ecosystem:

Chinese visa is 33x48mm, not 35x45 like Schengen, not square like US. Unique format.
Chinese visa COVA portal wants file size 40 KB to 1 MB, JPG only, 354x472 px minimum.
US DS-160 visa upload caps files at 240 KB. Square 600x600 minimum, 1200x1200 maximum.
Indian Sarathi driving licence requires 20-50 KB file size window (under or over both fail silently).
Indian PAN card is 25x35mm at 200x230 px maximum, 10-300 KB.
UK passport accepts light grey background in addition to white. One of few that does. Glasses banned since 2018.
German Personalausweis has a May 2025 rule requiring digital-only photos via Buergeramt for German citizens. Separate from German Schengen visa for foreign applicants, which still accepts standard 35x45mm digital photos.

These are the dataset's biggest non-obvious wins. If your tool gets these seven right, you cover the meaningfully different cases.

Validation methodology

For each country, I checked at least one of these sources:

US Department of State (travel.state.gov)
UK HM Passport Office (gov.uk/photos-for-passports)
German Bundesdruckerei + Auswaertiges Amt
Italian Polizia di Stato + Questura
French ANTS (ants.gouv.fr)
Spanish Ministerio de Asuntos Exteriores
Canadian IRCC (Immigration, Refugees and Citizenship Canada)
Australian Department of Foreign Affairs and Trade
Indian Passport Seva Kendra (passportindia.gov.in)
Indian RTO / Sarathi / Parivahan portals
Chinese Ministry of Foreign Affairs (cova.cs.mfa.gov.cn)
Japanese Ministry of Foreign Affairs (mofa.go.jp)
Schengen visa code Annex 11 (ICAO 9303)
EU Entry/Exit System (EES) specifications
New Zealand DIA (passports.govt.nz)
Brazilian Polícia Federal
Mexican SRE (gob.mx)

Beyond top-20 countries, I follow the ICAO 9303 default unless an official source documents a country-specific deviation. I do not pad the dataset with synthetic country variants. If a country's photo spec is identical to ICAO 9303 default, it is marked as such rather than counted as "unique".

This means the 100 country count is honest. I could have called it 193 (all ICAO member states) and claimed parity with competitors. I chose not to.

Architecture (in case you are building something similar)

The companion tool, IDPhotoSnap, runs the whole pipeline in the browser:

Face landmark detection via face-api.js (TF.js + WASM)
Background segmentation via BRIA RMBG-1.4 (ONNX Runtime Web)
Geometric cropping + JPEG export via Canvas API
Print-ready PDF via jsPDF

The photo never reaches a server. Verifiable in browser DevTools Network tab during the workflow - zero photo uploads, only static assets and ML model weights.

This matters because passport photos are biometric data under GDPR Article 9, Illinois BIPA, Texas CUBI, India DPDP Act 2023. Server-based architecture inherits compliance obligations; browser-only sidesteps the whole chain.

If you want a deeper writeup on the browser-only architecture and how to verify the claim, my privacy-first explainer covers the DevTools test in detail.

What I want from this

If you find a spec that is wrong, open an issue with a link to the official government source. If you want to add a country I do not have, open a PR with the spec plus the citation.

I will not accept specs copied from other photo tool aggregators. Government sources only - this is the data quality discipline that keeps the dataset from drifting into the same marketing inflation as the rest of the category.

Used in production

The dataset powers IDPhotoSnap. If you build something else with it, open a PR adding your project to the "Used by" section of the README.

DEV Community

I open-sourced passport photo specs for 100 countries (MIT, JSON, public API)

I open-sourced passport photo specs for 100 countries (MIT, JSON, public API)

What is in it

Three ways to use it

1. HTTP API (no clone)

2. NPM-style import

3. Plain JSON in any language

Why I bothered

Notable specs that catch tool builders

Validation methodology

Architecture (in case you are building something similar)

What I want from this

Used in production

Links

Top comments (0)