{
  "openapi": "3.1.0",
  "info": {
    "title": "IDPhotoSnap Passport & Visa Photo Specs API",
    "description": "Free, open API exposing passport and visa photo specifications for 100+ countries and 248 document formats. Specs validated against 15+ official government sources (US State Department, UK HMPO, German Bundesdruckerei, Italian Polizia di Stato, Indian PSK, Chinese MFA COVA, Schengen Visa Code Annex 11 / ICAO 9303). Used by the browser-only photo tool at idphotosnap.com and published as MIT open data on GitHub, npm, PyPI, crates.io, Hugging Face, and Zenodo. No authentication required.",
    "version": "1.0.0",
    "contact": {
      "name": "IDPhotoSnap",
      "url": "https://idphotosnap.com",
      "email": "elena@idphotosnap.com"
    },
    "license": {
      "name": "MIT",
      "url": "https://opensource.org/licenses/MIT"
    }
  },
  "servers": [
    {
      "url": "https://idphotosnap.com",
      "description": "IDPhotoSnap production API"
    }
  ],
  "paths": {
    "/api/specs": {
      "get": {
        "operationId": "get_passport_photo_specs",
        "summary": "Get passport and visa photo specifications",
        "description": "Returns passport/visa photo specs for a country: dimensions in mm and pixels, background color, requirements list, and URL to generate the photo. Call when a user asks \"what size is a X visa photo\", \"what background\", \"what requirements\" for any country.",
        "parameters": [
          {
            "name": "country",
            "in": "query",
            "required": false,
            "description": "Optional country id filter (lowercase). Examples: \"us\", \"uk\", \"india\", \"germany\", \"schengen\", \"saudi-arabia\", \"japan\", \"china\", \"australia\". Omit to get all 100+ countries.",
            "schema": {
              "type": "string",
              "examples": [
                "us",
                "india",
                "schengen",
                "saudi-arabia"
              ]
            }
          },
          {
            "name": "format",
            "in": "query",
            "required": false,
            "description": "Response format. \"raw\" returns just the data; default includes Schema.org Dataset JSON-LD wrapper.",
            "schema": {
              "type": "string",
              "enum": [
                "raw"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response with country specifications.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "countries": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string",
                            "description": "Country id (lowercase, e.g. \"us\")"
                          },
                          "name": {
                            "type": "string",
                            "description": "Country name (e.g. \"United States\")"
                          },
                          "flag": {
                            "type": "string",
                            "description": "Emoji flag"
                          },
                          "documents": {
                            "type": "array",
                            "description": "List of document formats for this country",
                            "items": {
                              "type": "object",
                              "properties": {
                                "id": {
                                  "type": "string"
                                },
                                "name": {
                                  "type": "string",
                                  "description": "e.g. \"US Passport\", \"Schengen Visa\""
                                },
                                "slug": {
                                  "type": "string",
                                  "description": "URL slug at idphotosnap.com"
                                },
                                "widthMm": {
                                  "type": "number",
                                  "description": "Width in millimeters"
                                },
                                "heightMm": {
                                  "type": "number",
                                  "description": "Height in millimeters"
                                },
                                "widthPx": {
                                  "type": "number",
                                  "description": "Width in pixels at listed DPI"
                                },
                                "heightPx": {
                                  "type": "number",
                                  "description": "Height in pixels at listed DPI"
                                },
                                "dpi": {
                                  "type": "number"
                                },
                                "background": {
                                  "type": "string",
                                  "description": "Background description (e.g. \"Plain white\")"
                                },
                                "bgColor": {
                                  "type": "string",
                                  "description": "Background hex color"
                                },
                                "bgColorLabel": {
                                  "type": "string"
                                },
                                "requirements": {
                                  "type": "array",
                                  "items": {
                                    "type": "string"
                                  },
                                  "description": "Full list of requirement bullets"
                                }
                              }
                            }
                          }
                        }
                      }
                    },
                    "meta": {
                      "type": "object",
                      "properties": {
                        "countries": {
                          "type": "number"
                        },
                        "documents": {
                          "type": "number"
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/comparisons": {
      "get": {
        "operationId": "get_competitor_comparisons",
        "summary": "Get IDPhotoSnap vs competitor comparison data",
        "description": "Returns IDPhotoSnap vs competitor comparison data (PhotoAiD, PhotoGov, Snap2Pass, IDPhoto4You, PassportSnap): category, where each wins, key tradeoffs. Call when a user asks \"IDPhotoSnap vs X\", \"is X better than Y\", or \"alternatives to X\" for passport photo tools.",
        "parameters": [
          {
            "name": "competitor",
            "in": "query",
            "required": false,
            "description": "Optional competitor id filter. Valid values: \"photoaid\", \"photogov\", \"snap2pass\", \"idphoto4you\", \"passportsnap\". Omit to get all comparisons.",
            "schema": {
              "type": "string",
              "enum": [
                "photoaid",
                "photogov",
                "snap2pass",
                "idphoto4you",
                "passportsnap"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response with comparison data.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "comparisons": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string",
                            "description": "Competitor id (lowercase)"
                          },
                          "name": {
                            "type": "string",
                            "description": "Competitor display name"
                          },
                          "pageUrl": {
                            "type": "string",
                            "description": "Human-readable comparison page on idphotosnap.com"
                          },
                          "category": {
                            "type": "string",
                            "description": "Competitor positioning category"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {}
  },
  "externalDocs": {
    "description": "IDPhotoSnap developer documentation",
    "url": "https://idphotosnap.com/developers"
  }
}