{
  "openapi": "3.1.0",
  "info": {
    "title": "Nationalize.io API",
    "description": "Free REST API that predicts the nationality of a person based on their first name using probabilistic models derived from a dataset of approximately one billion people spanning 250 countries and territories. Accepts single or batched names (up to 10), handles diacritics automatically, and returns ranked country probabilities as JSON using ISO 3166-1 alpha-2 codes. The same API key works across all three Demografix services (Genderize, Agify, Nationalize).",
    "version": "1.0.0",
    "termsOfService": "https://nationalize.io/legal/terms-and-conditions",
    "contact": {
      "url": "https://nationalize.io"
    }
  },
  "servers": [
    {
      "url": "https://api.nationalize.io",
      "description": "Production server"
    }
  ],
  "paths": {
    "/": {
      "get": {
        "operationId": "predictNationality",
        "summary": "Predict nationality from name",
        "description": "Predicts the nationality of one or more people based on their names, returning ranked country probabilities drawn from a dataset of approximately one billion people. Supports single name lookups, batched requests of up to 10 names, full name parsing, and diacritics handling. Results are returned as ISO 3166-1 alpha-2 country codes paired with probability scores, up to five countries per name.",
        "parameters": [
          {
            "name": "name",
            "in": "query",
            "required": true,
            "description": "A single name to predict nationality for. For batched lookups use the array form `name[]` repeated up to 10 times. Last names carry the strongest nationality signals; full names are also accepted and parsed automatically.",
            "schema": {
              "type": "string",
              "example": "nguyen"
            }
          },
          {
            "name": "name[]",
            "in": "query",
            "required": false,
            "description": "Batch form of the name parameter. Repeat up to 10 times to look up multiple names in a single request. Each name counts individually toward the monthly usage limit.",
            "schema": {
              "type": "array",
              "items": {
                "type": "string"
              },
              "maxItems": 10,
              "example": ["anna", "john", "kim"]
            },
            "style": "form",
            "explode": true
          },
          {
            "name": "apikey",
            "in": "query",
            "required": false,
            "description": "API authentication key. Required for paid plans and to track usage. Obtain at https://nationalize.io/login. The same key works across Genderize, Agify, and Nationalize.",
            "schema": {
              "type": "string",
              "example": "your_api_key_here"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Nationality prediction result. Returns a single object for a single name lookup, or an array of objects for a batched request.",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "$ref": "#/components/schemas/NationalityResult"
                    },
                    {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/NationalityResult"
                      }
                    }
                  ]
                },
                "examples": {
                  "single": {
                    "summary": "Single name lookup",
                    "value": {
                      "name": "nguyen",
                      "country": [
                        { "country_id": "VN", "probability": 0.561 },
                        { "country_id": "US", "probability": 0.035 },
                        { "country_id": "AU", "probability": 0.021 },
                        { "country_id": "CA", "probability": 0.016 },
                        { "country_id": "FR", "probability": 0.012 }
                      ],
                      "count": 360408
                    }
                  },
                  "not_found": {
                    "summary": "Name not found in dataset",
                    "value": {
                      "name": "zzzzunknown",
                      "country": null,
                      "count": 0
                    }
                  },
                  "batch": {
                    "summary": "Batched name lookup",
                    "value": [
                      {
                        "name": "anna",
                        "country": [
                          { "country_id": "FI", "probability": 0.083 },
                          { "country_id": "PL", "probability": 0.079 },
                          { "country_id": "SE", "probability": 0.071 },
                          { "country_id": "NO", "probability": 0.063 },
                          { "country_id": "DK", "probability": 0.058 }
                        ],
                        "count": 1234567
                      },
                      {
                        "name": "john",
                        "country": [
                          { "country_id": "US", "probability": 0.288 },
                          { "country_id": "GB", "probability": 0.195 },
                          { "country_id": "AU", "probability": 0.072 },
                          { "country_id": "CA", "probability": 0.065 },
                          { "country_id": "IE", "probability": 0.042 }
                        ],
                        "count": 987654
                      }
                    ]
                  }
                }
              }
            }
          },
          "402": {
            "description": "Payment Required. The monthly request quota has been exceeded on the free tier.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "error": "Request limit reached"
                }
              }
            }
          },
          "422": {
            "description": "Unprocessable Entity. The request is missing required parameters or contains invalid input.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "error": "Missing 'name' parameter"
                }
              }
            }
          },
          "429": {
            "description": "Too Many Requests. Monthly usage limit exceeded. Resets at the start of the next billing cycle.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "error": "Request limit reached"
                }
              }
            }
          }
        },
        "tags": ["Nationality"]
      }
    }
  },
  "components": {
    "schemas": {
      "NationalityResult": {
        "type": "object",
        "description": "Nationality prediction for a single name",
        "properties": {
          "name": {
            "type": "string",
            "description": "The input name as submitted in the request"
          },
          "country": {
            "description": "Ranked list of up to five predicted nationalities with probability scores. Null when the name is not found in the dataset after all matching attempts (direct match, diacritics removal, full name parsing).",
            "oneOf": [
              {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/CountryProbability"
                },
                "maxItems": 5
              },
              {
                "type": "null"
              }
            ]
          },
          "count": {
            "type": "integer",
            "description": "Number of data points used in the prediction",
            "minimum": 0,
            "example": 360408
          }
        },
        "required": ["name", "country", "count"]
      },
      "CountryProbability": {
        "type": "object",
        "description": "A country prediction with its associated probability score",
        "properties": {
          "country_id": {
            "type": "string",
            "description": "ISO 3166-1 alpha-2 country code",
            "pattern": "^[A-Z]{2}$",
            "example": "VN"
          },
          "probability": {
            "type": "number",
            "format": "double",
            "description": "Confidence score for this nationality, between 0 and 1. The sum of all probabilities in the array may be less than 1 as only the top five results are returned.",
            "minimum": 0,
            "maximum": 1,
            "example": 0.561
          }
        },
        "required": ["country_id", "probability"]
      },
      "ErrorResponse": {
        "type": "object",
        "description": "Error response from the API",
        "properties": {
          "error": {
            "type": "string",
            "description": "Human-readable error message describing the problem"
          }
        },
        "required": ["error"]
      }
    },
    "securitySchemes": {
      "apiKey": {
        "type": "apiKey",
        "in": "query",
        "name": "apikey",
        "description": "API key obtained from https://nationalize.io/login. The same key is shared across all three Demografix services (Genderize, Agify, Nationalize)."
      }
    }
  },
  "tags": [
    {
      "name": "Nationality",
      "description": "Operations for predicting nationality from names"
    }
  ]
}