{
  "openapi": "3.0.1",
  "info": {
    "title": "sthan.io API",
    "description": "Address and location data APIs for developers. Includes address autocomplete, parsing, verification, geocoding, reverse geocoding (USA), address autocomplete (India), and IP geolocation (global). All endpoints require JWT Bearer authentication — call GET /Auth/Token first to obtain a token.",
    "termsOfService": "https://sthan.io/home/privacy",
    "contact": {
      "name": "sthan.io",
      "url": "https://sthan.io",
      "email": "support@sthan.io"
    },
    "license": {
      "name": "Commercial",
      "url": "https://sthan.io/home/privacy"
    },
    "version": "v1"
  },
  "paths": {
    "/v2/address-parser/usa/{mode}/{address}": {
      "get": {
        "tags": [
          "AddressParserUsa"
        ],
        "summary": "Parse a freeform US address into structured components, V2.",
        "parameters": [
          {
            "name": "address",
            "in": "path",
            "description": "Freeform address string (URL-encoded).",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "mode",
            "in": "path",
            "description": "How hard the match may work to find the address:\n\n| Mode | What it does |\n|---|---|\n| strict | Only postal-confirmed exact matches. Error on a miss. |\n| balanced | Exact plus typo-corrected matches. Best match returned with deliverableStatus=Unknown when the postal check is missing. |\n| fuzzy | Everything in balanced plus wider wildcard matching. Higher recovery. |\n| speculative | Loosest recovery with wider street-name typo tolerance. House number, direction, state and street name are never substituted. Such results are reported as matchTier=Speculative. |",
            "required": true,
            "schema": {
              "enum": [
                "strict",
                "balanced",
                "fuzzy",
                "speculative"
              ],
              "type": "string",
              "default": "speculative",
              "x-enum-descriptions": [
                "postal-confirmed exact matches only",
                "exact plus typo-corrected matches",
                "balanced plus wider wildcard matching",
                "loosest recovery, wider street typo tolerance"
              ]
            }
          },
          {
            "name": "match",
            "in": "query",
            "description": "Optional query-based mode (`?match=balanced`). Default `balanced`. Header `X-Sthan-Match` is equivalent.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "text/plain": {
                "schema": {
                  "$ref": "#/components/schemas/V2ParsedAddressModel"
                }
              },
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V2ParsedAddressModel"
                }
              },
              "text/json": {
                "schema": {
                  "$ref": "#/components/schemas/V2ParsedAddressModel"
                }
              }
            }
          },
          "400": {
            "description": "Bad Request"
          },
          "404": {
            "description": "Not Found"
          },
          "429": {
            "description": "Too Many Requests"
          },
          "500": {
            "description": "Internal Server Error"
          }
        },
        "x-ai-when-to-use": "Use when the user has an unstructured or messy address string and needs it broken into structured components (street number, street name, unit, city, state, ZIP). Also use when the user says 'parse', 'split', 'extract', 'break down', or 'structure this address'. Handles abbreviations, missing punctuation, and transposed components.",
        "x-ai-not-for": "If the user wants to know whether the address is deliverable, use Address Verification instead. If the user needs coordinates, use Forward Geocoding instead.",
        "x-ai-example-prompts": [
          "Parse 'apt 2b 500 broadway new york ny 10012' into components",
          "Break down this address: 123 N Main St Ste 200 Chicago IL",
          "What are the parts of this address?",
          "Extract the ZIP code and city from this address",
          "Split this into street, city, state, zip"
        ],
        "x-ai-response-interpretation": {
          "MatchTier = Exact": "Every component matched and the postal authority confirms the address. Confidence is 1.0.",
          "MatchTier = Near": "One or more components were typo-corrected; the address is still postal-confirmed. Safe to use, tell the user what changed.",
          "MatchTier = Approximate": "Several components were corrected or the street was straightened from reference data. Read MatchCode before trusting a field.",
          "MatchTier = Speculative": "Best-effort recovery with wide typo tolerance, no guarantee. Only returned in speculative mode. Always show it to the user for confirmation.",
          "MatchTier = None": "No candidate passed the requested mode. Read Footnotes for the reason.",
          "MatchCode.<field> = Matched": "The field came back identical to the input.",
          "MatchCode.<field> = Corrected": "The input value was wrong but recoverable; the result holds the authoritative value. Show the user the change.",
          "MatchCode.<field> = Inferred": "The field was missing from the input and filled from reference data (for example Zip4 or City from the ZIP).",
          "MatchCode.<field> = Unmatched": "The field was supplied but could not be confirmed; the result echoes the input unverified.",
          "MatchCode.<field> = NotApplicable": "The field was not in the input and could not be derived.",
          "Footnotes contains HouseNumberMismatch / NumericStreetMismatch / StateMismatch / DirectionMismatch / StreetTypeMismatch / StreetNameMismatch": "The named component in the input disagreed with every candidate, so no substitution was made. Ask the user to check that component.",
          "Footnotes contains UnknownRejection": "The candidate was rejected for a reason not covered by the other footnotes. Treat as not found.",
          "Footnotes empty": "Nothing was rejected.",
          "Confidence >= 0.95": "Exact match; all parsed components are highly reliable.",
          "Confidence 0.85-0.94": "High confidence; minor normalization applied.",
          "Confidence 0.70-0.84": "Medium confidence; some components were inferred or corrected, present to the user for confirmation.",
          "Confidence < 0.70": "Low confidence; ask the user to verify the parsed result. Speculative results are capped at 0.70."
        },
        "x-ai-next-actions": {
          "MatchTier = Exact or Near": "Use the parsed components directly. If deliverability is needed, call Address Verification with the FullAddress.",
          "MatchTier = Approximate": "Use the fields whose MatchCode is Matched or Inferred; show the Corrected ones to the user before relying on them.",
          "MatchTier = Speculative": "Present the parsed result to the user and ask them to confirm before using it downstream.",
          "MatchTier = None": "Tell the user which component the Footnotes name and ask them to correct it, then retry. Do not guess a replacement.",
          "Any MatchCode.<field> = Unmatched": "Treat that field as unverified user input; ask for it again if it matters downstream."
        }
      }
    },
    "/v2/address-verification/usa/{mode}/{address}": {
      "get": {
        "tags": [
          "AddressVerificationUsa"
        ],
        "summary": "Verify a US address, V2.",
        "parameters": [
          {
            "name": "address",
            "in": "path",
            "description": "Freeform address string (URL-encoded).",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "mode",
            "in": "path",
            "description": "How hard the match may work to find the address:\n\n| Mode | What it does |\n|---|---|\n| strict | Only postal-confirmed exact matches. Error on a miss. |\n| balanced | Exact plus typo-corrected matches. Best match returned with deliverableStatus=Unknown when the postal check is missing. |\n| fuzzy | Everything in balanced plus wider wildcard matching. Higher recovery. |\n| speculative | Loosest recovery with wider street-name typo tolerance. House number, direction, state and street name are never substituted. Such results are reported as matchTier=Speculative. |",
            "required": true,
            "schema": {
              "enum": [
                "strict",
                "balanced",
                "fuzzy",
                "speculative"
              ],
              "type": "string",
              "default": "speculative",
              "x-enum-descriptions": [
                "postal-confirmed exact matches only",
                "exact plus typo-corrected matches",
                "balanced plus wider wildcard matching",
                "loosest recovery, wider street typo tolerance"
              ]
            }
          },
          {
            "name": "match",
            "in": "query",
            "description": "Optional query-based mode (`?match=balanced`). Default `balanced`. Header `X-Sthan-Match` is equivalent.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "text/plain": {
                "schema": {
                  "$ref": "#/components/schemas/V2VerifiedAddressModel"
                }
              },
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V2VerifiedAddressModel"
                }
              },
              "text/json": {
                "schema": {
                  "$ref": "#/components/schemas/V2VerifiedAddressModel"
                }
              }
            }
          },
          "400": {
            "description": "Bad Request"
          },
          "404": {
            "description": "Not Found"
          },
          "429": {
            "description": "Too Many Requests"
          },
          "500": {
            "description": "Internal Server Error"
          }
        },
        "x-ai-when-to-use": "Use when the user wants to check if a US address is real, valid, or deliverable. Also use when the user says 'validate', 'check', 'verify', or 'is this address valid'. Accepts freeform text input — abbreviations, missing punctuation, and messy formatting are all handled.",
        "x-ai-not-for": "Do not use for non-US addresses. If the user only needs coordinates (lat/long), use Forward Geocoding instead. If the user only needs the address broken into components without deliverability check, use Address Parser instead.",
        "x-ai-example-prompts": [
          "Is 123 Main St New York a real address?",
          "Verify this address for me: 456 Oak Ave, Los Angeles, CA",
          "Check if my customer's address is deliverable",
          "Can mail be delivered to this address?",
          "Is this a valid mailing address?"
        ],
        "x-ai-response-interpretation": {
          "DeliverableStatus = Confirmed": "Primary + secondary fully confirmed by postal authority — safe to ship",
          "DeliverableStatus = ConfirmedPrimaryOnly": "Primary number confirmed; secondary unit was missing or invalid — ask the user for the unit",
          "DeliverableStatus = NotDeliverable": "Postal authority explicitly rejected the primary number — do not ship",
          "DeliverableStatus = Unknown": "No postal confirmation on file — address may exist but we cannot vouch for deliverability",
          "DpvConfirmation = Y": "Underlying USPS DPV code: primary + secondary confirmed (equivalent to DeliverableStatus = Confirmed)",
          "DpvConfirmation = N": "Underlying USPS DPV code: primary not confirmed (equivalent to DeliverableStatus = NotDeliverable)",
          "DpvConfirmation = S": "Underlying USPS DPV code: primary confirmed, secondary invalid (rolls up to ConfirmedPrimaryOnly)",
          "DpvConfirmation = D": "Underlying USPS DPV code: primary confirmed, secondary missing (rolls up to ConfirmedPrimaryOnly)",
          "RecordType = H": "Highrise (apartment building)",
          "RecordType = S": "Street address (individual house)",
          "RecordType = F": "Firm/business address",
          "RecordType = P": "PO Box",
          "MatchTier = Exact": "Every component matched and the postal authority confirms the address.",
          "MatchTier = Near": "One or more components were typo-corrected; still postal-confirmed. Tell the user what changed.",
          "MatchTier = Approximate": "Several components were corrected. Read MatchCode before trusting a field.",
          "MatchTier = Speculative": "Best-effort recovery, no guarantee. Only in speculative mode. Always confirm with the user.",
          "MatchTier = None": "No candidate passed the requested mode. Read Footnotes for the reason.",
          "MatchCode.<field> = Matched": "The field came back identical to the input.",
          "MatchCode.<field> = Corrected": "The input value was wrong but recoverable; the result holds the authoritative value. Show the user the change.",
          "MatchCode.<field> = Inferred": "The field was missing from the input and filled from reference data (for example Zip4).",
          "MatchCode.<field> = Unmatched": "The field was supplied but could not be confirmed; the result echoes the input unverified.",
          "MatchCode.Unit = Unmatched with DeliverableStatus = ConfirmedPrimaryOnly": "The building is real but the unit is not; ask the user for the correct unit.",
          "Footnotes contains HouseNumberMismatch / NumericStreetMismatch / StateMismatch / DirectionMismatch / StreetTypeMismatch / StreetNameMismatch": "The named component in the input disagreed with every candidate, so no substitution was made. Ask the user to check that component.",
          "Footnotes contains UnknownRejection": "The candidate was rejected for a reason not covered by the other footnotes. Treat as not verified.",
          "Footnotes empty": "Nothing was rejected."
        },
        "x-ai-next-actions": {
          "DeliverableStatus = ConfirmedPrimaryOnly": "Ask the user: 'What is the apartment or unit number?' Then re-verify with the unit included.",
          "DeliverableStatus = Confirmed, need coordinates": "Call Forward Geocoding with the verified FullAddress to get lat/long.",
          "DeliverableStatus = NotDeliverable": "Tell the user the address could not be verified. Suggest they double-check spelling, city, state, and ZIP.",
          "DeliverableStatus = Unknown": "Treat as best-effort match. Suggest the user confirm the address before relying on it for shipping.",
          "MatchTier = None": "Tell the user which component the Footnotes name and ask them to correct it, then retry. Do not guess a replacement.",
          "MatchTier = Speculative or Approximate": "Show the Corrected fields from MatchCode to the user and get a yes before shipping or storing.",
          "Any MatchCode.<field> = Corrected": "Say what was changed, for example 'I corrected the ZIP from 10011 to 10012'."
        }
      }
    },
    "/auth/token": {
      "get": {
        "tags": [
          "Auth"
        ],
        "summary": "Obtain a JWT Bearer token for API authentication.",
        "parameters": [
          {
            "name": "profileName",
            "in": "header",
            "description": "Your profile name (GUID issued at signup).",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "profilePassword",
            "in": "header",
            "description": "Your profile password.",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Returns the JWT access token and expiration."
          },
          "401": {
            "description": "Invalid profile name or password.",
            "content": {
              "text/plain": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              },
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              },
              "text/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error."
          }
        },
        "x-ai-when-to-use": "Use to obtain a JWT Bearer token for authenticating all other API calls. Requires profileName and profilePassword headers. The returned token must be used as 'Authorization: Bearer {access_token}' on all subsequent requests.",
        "x-ai-not-for": "This endpoint only returns a token — it does not verify addresses, geocode, or perform any data operations.",
        "x-ai-example-prompts": [
          "Get an API token",
          "Authenticate with the API",
          "I need to log in to the sthan API"
        ],
        "x-ai-response-interpretation": {
          "access_token": "The JWT token to use in Authorization headers",
          "expiration": "When the token expires — obtain a new one before this time"
        },
        "x-ai-notes": "Token lifetime is capped at 60 minutes. Token is valid immediately upon issuance."
      }
    },
    "/autocomplete/ind/city/displaytype/{displayType}/{text}": {
      "get": {
        "tags": [
          "AutoCompleteIndia"
        ],
        "summary": "Gets a list of cities based on the display type and search text.",
        "parameters": [
          {
            "name": "text",
            "in": "path",
            "description": "The search text.",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "displayType",
            "in": "path",
            "description": "Format of each suggestion returned:\n\n| Value | Returns | Example |\n|---|---|---|\n| 0 | City, State | Mumbai, Maharashtra |\n| 1 | City, StateCode | Mumbai, MH |",
            "required": true,
            "schema": {
              "enum": [
                0,
                1
              ],
              "type": "integer",
              "format": "int32",
              "default": 0,
              "x-enum-descriptions": [
                "City, State",
                "City, StateCode"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Returns a list of cities.",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "array",
                  "items": {
                    "type": "string"
                  }
                }
              },
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "type": "string"
                  }
                }
              },
              "text/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "type": "string"
                  }
                }
              }
            }
          },
          "400": {
            "description": "If the search text is null or empty."
          },
          "429": {
            "description": "Too Many Requests"
          },
          "500": {
            "description": "If there is an internal server error."
          }
        }
      }
    },
    "/autocomplete/ind/locality/displaytype/{displayType}/{text}": {
      "get": {
        "tags": [
          "AutoCompleteIndia"
        ],
        "summary": "Gets a list of localities based on the display type and search text.",
        "parameters": [
          {
            "name": "text",
            "in": "path",
            "description": "The search text.",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "displayType",
            "in": "path",
            "description": "Format of each suggestion returned:\n\n| Value | Returns | Example |\n|---|---|---|\n| 0 | Locality, City, State - PinCode | Ambewadi, Mumbai, Maharashtra - 400004 |\n| 1 | Locality, City, StateCode - PinCode | Ambewadi, Mumbai, MH - 400004 |",
            "required": true,
            "schema": {
              "enum": [
                0,
                1
              ],
              "type": "integer",
              "format": "int32",
              "default": 0,
              "x-enum-descriptions": [
                "Locality, City, State - PinCode",
                "Locality, City, StateCode - PinCode"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Returns a list of localities.",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "array",
                  "items": {
                    "type": "string"
                  }
                }
              },
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "type": "string"
                  }
                }
              },
              "text/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "type": "string"
                  }
                }
              }
            }
          },
          "400": {
            "description": "If the search text is null or empty."
          },
          "429": {
            "description": "Too Many Requests"
          },
          "500": {
            "description": "If there is an internal server error."
          }
        }
      }
    },
    "/autocomplete/ind/pincode/displaytype/{displayType}/{text}": {
      "get": {
        "tags": [
          "AutoCompleteIndia"
        ],
        "summary": "Gets a list of pin codes based on the display type and search text.",
        "parameters": [
          {
            "name": "text",
            "in": "path",
            "description": "The search text.",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "displayType",
            "in": "path",
            "description": "Format of each suggestion returned:\n\n| Value | Returns | Example |\n|---|---|---|\n| 0 | PinCode, City, State | 400001, Mumbai, Maharashtra |\n| 1 | PinCode, City, StateCode | 400001, Mumbai, MH |\n| 2 | PinCode, PostOffice, City, State | 400001, Bazargate, Mumbai, Maharashtra |\n| 3 | PinCode, PostOffice, City, StateCode | 400001, Bazargate, Mumbai, MH |",
            "required": true,
            "schema": {
              "enum": [
                0,
                1,
                2,
                3
              ],
              "type": "integer",
              "format": "int32",
              "default": 0,
              "x-enum-descriptions": [
                "PinCode, City, State",
                "PinCode, City, StateCode",
                "PinCode, PostOffice, City, State",
                "PinCode, PostOffice, City, StateCode"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Returns a list of pin codes.",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "array",
                  "items": {
                    "type": "string"
                  }
                }
              },
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "type": "string"
                  }
                }
              },
              "text/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "type": "string"
                  }
                }
              }
            }
          },
          "400": {
            "description": "If the search text is null or empty."
          },
          "429": {
            "description": "Too Many Requests"
          },
          "500": {
            "description": "If there is an internal server error."
          }
        }
      }
    },
    "/autocomplete/usa/address/{text}": {
      "get": {
        "tags": [
          "AutoCompleteUsa"
        ],
        "summary": "Retrieves autocomplete suggestions for a given address text.",
        "parameters": [
          {
            "name": "text",
            "in": "path",
            "description": "The input text for address autocomplete.",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "array",
                  "items": {
                    "type": "string"
                  }
                }
              },
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "type": "string"
                  }
                }
              },
              "text/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "type": "string"
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad Request"
          },
          "429": {
            "description": "Too Many Requests"
          },
          "500": {
            "description": "Internal Server Error"
          }
        },
        "x-ai-when-to-use": "Use when the user is typing an address and wants suggestions or completions. Also use when building type-ahead search. Sub-100ms response time. Returns an array of complete address strings, not objects.",
        "x-ai-not-for": "Do not use for address verification (use Address Verification). Do not use for parsing an already-complete address (use Address Parser). For city-only or ZIP-only autocomplete, use the dedicated City or ZipCode autocomplete endpoints.",
        "x-ai-example-prompts": [
          "Suggest addresses starting with '123 Main'",
          "Autocomplete this partial address: 456 Oak",
          "What addresses match '1600 Penn'?",
          "Complete this address for me"
        ],
        "x-ai-response-interpretation": {
          "Result is array of strings": "Each string is a complete, formatted address suggestion ranked by relevance",
          "Empty array": "No matching addresses found — the input may be too short (try 3+ characters) or too ambiguous"
        },
        "x-ai-notes": "Minimum input of 3 characters is recommended for useful results. Results are cached for 90 days."
      }
    },
    "/autocomplete/usa/city/displaytype/{displayType}/{text}": {
      "get": {
        "tags": [
          "AutoCompleteUsa"
        ],
        "summary": "Retrieves autocomplete suggestions for a given city text.",
        "parameters": [
          {
            "name": "text",
            "in": "path",
            "description": "The input text for city autocomplete.",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "displayType",
            "in": "path",
            "description": "Format of each suggestion returned:\n\n| Value | Returns | Example |\n|---|---|---|\n| 0 | City, StateCode | Austin, TX |\n| 1 | City, State | Austin, Texas |",
            "required": true,
            "schema": {
              "enum": [
                0,
                1
              ],
              "type": "integer",
              "format": "int32",
              "default": 0,
              "x-enum-descriptions": [
                "City, StateCode",
                "City, State"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "array",
                  "items": {
                    "type": "string"
                  }
                }
              },
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "type": "string"
                  }
                }
              },
              "text/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "type": "string"
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad Request"
          },
          "429": {
            "description": "Too Many Requests"
          },
          "500": {
            "description": "Internal Server Error"
          }
        },
        "x-ai-when-to-use": "Use when the user needs US city name suggestions from partial input. DisplayType 0 returns 'City, StateCode' (e.g., 'New York, NY'). DisplayType 1 returns 'City, State' (e.g., 'New York, New York').",
        "x-ai-not-for": "For full address autocomplete, use the Address autocomplete endpoint. For ZIP code lookup, use the ZipCode autocomplete endpoint.",
        "x-ai-example-prompts": [
          "What US cities start with 'San'?",
          "Suggest cities matching 'New Y'",
          "Autocomplete this city name"
        ]
      }
    },
    "/autocomplete/usa/zipcode/displaytype/{displayType}/{text}": {
      "get": {
        "tags": [
          "AutoCompleteUsa"
        ],
        "summary": "Retrieves autocomplete suggestions for a given ZIP code text.",
        "parameters": [
          {
            "name": "text",
            "in": "path",
            "description": "The input text for ZIP code autocomplete.",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "displayType",
            "in": "path",
            "description": "Format of each suggestion returned:\n\n| Value | Returns | Example |\n|---|---|---|\n| 0 | ZipCode, City, StateCode | 78712, Austin, TX |\n| 1 | ZipCode, City, State | 78712, Austin, Texas |\n| 2 | ZipCode-Zip4, City, StateCode | 60107-1147, Streamwood, IL |\n| 3 | ZipCode-Zip4, City, State | 60107-1147, Streamwood, Illinois |",
            "required": true,
            "schema": {
              "enum": [
                0,
                1,
                2,
                3
              ],
              "type": "integer",
              "format": "int32",
              "default": 0,
              "x-enum-descriptions": [
                "ZipCode, City, StateCode",
                "ZipCode, City, State",
                "ZipCode-Zip4, City, StateCode",
                "ZipCode-Zip4, City, State"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "array",
                  "items": {
                    "type": "string"
                  }
                }
              },
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "type": "string"
                  }
                }
              },
              "text/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "type": "string"
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad Request"
          },
          "429": {
            "description": "Too Many Requests"
          },
          "500": {
            "description": "Internal Server Error"
          }
        },
        "x-ai-when-to-use": "Use when the user needs US ZIP code suggestions from partial input. DisplayType 0='ZIP, StateCode', 1='ZIP, State', 2='ZIP-ZIP4, StateCode', 3='ZIP-ZIP4, State'.",
        "x-ai-not-for": "For full address autocomplete, use the Address autocomplete endpoint. For city lookup, use the City autocomplete endpoint.",
        "x-ai-example-prompts": [
          "What ZIP codes start with '100'?",
          "Find ZIP codes matching '9021'",
          "Suggest ZIP codes for this area"
        ]
      }
    },
    "/geocoding/usa/forward/{address}": {
      "get": {
        "tags": [
          "GeocodingUsa"
        ],
        "summary": "Geocode a USA address to coordinates (latitude/longitude)",
        "parameters": [
          {
            "name": "address",
            "in": "path",
            "description": "USA address to geocode (e.g., \"1600 Pennsylvania Ave NW, Washington, DC 20500\")",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Returns the geocoded result with coordinates",
            "content": {
              "text/plain": {
                "schema": {
                  "$ref": "#/components/schemas/GeocodingResult"
                }
              },
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GeocodingResult"
                }
              },
              "text/json": {
                "schema": {
                  "$ref": "#/components/schemas/GeocodingResult"
                }
              }
            }
          },
          "400": {
            "description": "Invalid or missing address parameter"
          },
          "404": {
            "description": "Address not found after trying all sources"
          },
          "429": {
            "description": "Rate limit exceeded"
          },
          "500": {
            "description": "Internal server error"
          }
        },
        "x-ai-when-to-use": "Use when the user needs latitude/longitude coordinates for a US address. Also use when the user says 'geocode', 'get coordinates', 'lat/long', 'plot on map', or 'where is this'. Accepts freeform address text.",
        "x-ai-not-for": "If the user has coordinates and needs an address, use Reverse Geocoding instead. If the user wants to know if the address is deliverable, use Address Verification instead.",
        "x-ai-example-prompts": [
          "Get coordinates for 1600 Pennsylvania Ave, Washington DC",
          "What are the lat/long for the White House?",
          "Geocode this address so I can plot it on a map",
          "Where exactly is 123 Main St, New York?"
        ],
        "x-ai-response-interpretation": {
          "accuracy.type = rooftop": "Exact building-level coordinates — highest precision",
          "accuracy.type = interpolated": "Estimated position along a street range — good for mapping but not exact. Check interpolation.estimatedAccuracyMeters for precision.",
          "accuracy.type = centroid": "Center of a geographic area (ZIP code or city) — area-level only, not suitable for navigation",
          "accuracy.type = approximate": "Low-precision estimate — use with caution",
          "confidence >= 0.90": "High confidence — coordinates pinpoint the location",
          "confidence 0.50-0.89": "Moderate confidence — suitable for mapping but not precise navigation",
          "confidence < 0.50": "Low confidence — coordinates may be significantly off, warn the user",
          "source = 10": "Primary database (highest quality)",
          "source = 40": "Interpolated from street range",
          "source = 42": "Area centroid (lowest precision)"
        },
        "x-ai-next-actions": {
          "Need to verify the address too": "Call Address Verification with the same address to check deliverability.",
          "accuracy.type = centroid": "Warn the user that coordinates are approximate. Ask for a more specific address."
        },
        "x-ai-notes": "Forward geocoding uses camelCase JSON field names (e.g., inputAddress, formattedAddress, location.latitude), unlike other endpoints which use PascalCase."
      }
    },
    "/geocoding/usa/reverse/{lat}/{lon}": {
      "get": {
        "tags": [
          "GeocodingUsa"
        ],
        "summary": "Reverse geocode coordinates to USA address",
        "parameters": [
          {
            "name": "lat",
            "in": "path",
            "description": "Latitude (-90 to 90)",
            "required": true,
            "schema": {
              "type": "number",
              "format": "double"
            }
          },
          {
            "name": "lon",
            "in": "path",
            "description": "Longitude (-180 to 180)",
            "required": true,
            "schema": {
              "type": "number",
              "format": "double"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "description": "Addresses to return, 1 to 10 (default 1): the nearest, plus up to limit - 1 other nearby addresses in \"nearby\", one per building",
            "schema": {
              "type": "integer",
              "format": "int32",
              "default": 1
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Returns the address for the coordinates",
            "content": {
              "text/plain": {
                "schema": {
                  "$ref": "#/components/schemas/ReverseGeocodingResult"
                }
              },
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ReverseGeocodingResult"
                }
              },
              "text/json": {
                "schema": {
                  "$ref": "#/components/schemas/ReverseGeocodingResult"
                }
              }
            }
          },
          "400": {
            "description": "Invalid coordinates"
          },
          "404": {
            "description": "No address found near the coordinates"
          },
          "429": {
            "description": "Rate limit exceeded"
          },
          "500": {
            "description": "Internal server error"
          }
        },
        "x-ai-when-to-use": "Use when the user has latitude/longitude coordinates and wants the nearest US street address. Also use when the user says 'reverse geocode', 'what address is at these coordinates', or 'find the nearest address'.",
        "x-ai-not-for": "If the user has an address and needs coordinates, use Forward Geocoding instead.",
        "x-ai-example-prompts": [
          "What address is at 40.7128, -74.0060?",
          "Find the nearest address to coordinates 38.8977, -77.0365",
          "Reverse geocode these lat/long values",
          "What building is at these coordinates?"
        ],
        "x-ai-response-interpretation": {
          "distance = 0": "Exact match — coordinates are at the address location",
          "distance < 50 meters": "Very close — likely the correct address",
          "distance > 500 meters": "The nearest address is far — coordinates may be in an area without street addresses (park, water, rural area)",
          "confidence >= 0.90": "High confidence — the returned address is very likely correct",
          "confidence < 0.50": "Low confidence — the nearest address may not be meaningful for these coordinates"
        },
        "x-ai-notes": "Reverse geocoding uses camelCase JSON field names. Distance is in meters. Latitude must be -90 to 90, longitude must be -180 to 180."
      }
    },
    "/ipgeolocation/{ip}": {
      "get": {
        "tags": [
          "IpGeolocation"
        ],
        "summary": "Retrieves geolocation and network information for a given IP address (IPv4 or IPv6).",
        "parameters": [
          {
            "name": "ip",
            "in": "path",
            "description": "The IP address to lookup (e.g., 8.8.8.8 or 2001:4860:4860::8888).",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "text/plain": {
                "schema": {
                  "$ref": "#/components/schemas/GeoLocation"
                }
              },
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GeoLocation"
                }
              },
              "text/json": {
                "schema": {
                  "$ref": "#/components/schemas/GeoLocation"
                }
              }
            }
          },
          "400": {
            "description": "Bad Request"
          },
          "404": {
            "description": "Not Found"
          },
          "429": {
            "description": "Too Many Requests"
          },
          "500": {
            "description": "Internal Server Error"
          }
        },
        "x-ai-when-to-use": "Use when the user wants to know the geographic location of an IP address. Supports both IPv4 (e.g., 8.8.8.8) and IPv6 (e.g., 2001:4860:4860::8888). Also use when the user says 'where is this IP', 'IP lookup', 'geolocate this IP', or 'what country is this IP from'.",
        "x-ai-not-for": "Do not use for address-to-coordinates conversion (use Forward Geocoding). Private/reserved IPs (127.0.0.1, 10.x.x.x, 192.168.x.x) will not return useful location data.",
        "x-ai-example-prompts": [
          "Where is IP 8.8.8.8 located?",
          "What country is this IP address from: 1.2.3.4?",
          "Get the geolocation for this IP",
          "Look up the location of 203.0.113.50"
        ],
        "x-ai-response-interpretation": {
          "Country accuracy": "Country-level accuracy is typically 99%+",
          "City accuracy": "City-level accuracy is typically 80-90% — not guaranteed to be exact",
          "Latitude/Longitude": "Approximate center of the identified area, not exact user location",
          "Precision": "city, region or country: how far down the answer goes. With region or country the city is absent and coordinates and local time are for that area's centre",
          "Confidence": "0 to 1, how strongly independent checks agreed on the city. Absent when the address is new to us (ask again in a few seconds) or when they did not agree well enough",
          "IsHosting / IsProxy / IsMobile": "Data-centre, cloud or anycast address; known proxy or VPN exit; mobile carrier. A hosting or proxy address does not locate a person",
          "Asn / AsName / Isp / Organization / ReverseDns": "The network that owns the address and its reverse DNS name when one exists"
        },
        "x-ai-notes": "IP Geolocation uses PascalCase field names: IpAddress, Country, CountryCode, CountryNativeName, Region, RegionCode, City, PostalCode, Latitude, Longitude, Continent, ContinentCode, Timezone, TimezoneDetail (Id, UtcOffset, OffsetSeconds, IsDst, CurrentLocalTime), Type, Precision, IsEu, CallingCode, Capital, Borders, Currency (Code, Name, Symbol), Languages, Tld, Flag (Emoji, Svg), Asn, AsName, Isp, Organization, IsMobile, IsProxy, IsHosting, ReverseDns, Confidence."
      }
    }
  },
  "components": {
    "schemas": {
      "DeliverableStatus": {
        "enum": [
          "Unknown",
          "Confirmed",
          "ConfirmedPrimaryOnly",
          "NotDeliverable"
        ],
        "type": "string"
      },
      "GeoCurrency": {
        "type": "object",
        "properties": {
          "code": {
            "type": "string",
            "nullable": true
          },
          "name": {
            "type": "string",
            "nullable": true
          },
          "symbol": {
            "type": "string",
            "nullable": true
          }
        },
        "additionalProperties": false
      },
      "GeoFlag": {
        "type": "object",
        "properties": {
          "emoji": {
            "type": "string",
            "nullable": true
          },
          "svg": {
            "type": "string",
            "nullable": true
          }
        },
        "additionalProperties": false
      },
      "GeoLocation": {
        "type": "object",
        "properties": {
          "ipAddress": {
            "type": "string",
            "nullable": true
          },
          "country": {
            "type": "string",
            "nullable": true
          },
          "countryCode": {
            "type": "string",
            "nullable": true
          },
          "region": {
            "type": "string",
            "nullable": true
          },
          "city": {
            "type": "string",
            "nullable": true
          },
          "latitude": {
            "type": "number",
            "format": "double"
          },
          "longitude": {
            "type": "number",
            "format": "double"
          },
          "continent": {
            "type": "string",
            "nullable": true
          },
          "timezone": {
            "type": "string",
            "nullable": true
          },
          "postalCode": {
            "type": "string",
            "nullable": true
          },
          "type": {
            "type": "string",
            "nullable": true
          },
          "precision": {
            "type": "string",
            "nullable": true
          },
          "continentCode": {
            "type": "string",
            "nullable": true
          },
          "regionCode": {
            "type": "string",
            "nullable": true
          },
          "countryNativeName": {
            "type": "string",
            "nullable": true
          },
          "isEu": {
            "type": "boolean",
            "nullable": true
          },
          "callingCode": {
            "type": "string",
            "nullable": true
          },
          "capital": {
            "type": "string",
            "nullable": true
          },
          "borders": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "nullable": true
          },
          "currency": {
            "$ref": "#/components/schemas/GeoCurrency"
          },
          "languages": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "nullable": true
          },
          "tld": {
            "type": "string",
            "nullable": true
          },
          "flag": {
            "$ref": "#/components/schemas/GeoFlag"
          },
          "timezoneDetail": {
            "$ref": "#/components/schemas/GeoTimezoneDetail"
          },
          "asn": {
            "type": "integer",
            "format": "int32",
            "nullable": true
          },
          "asName": {
            "type": "string",
            "nullable": true
          },
          "isp": {
            "type": "string",
            "nullable": true
          },
          "organization": {
            "type": "string",
            "nullable": true
          },
          "isMobile": {
            "type": "boolean",
            "nullable": true
          },
          "isProxy": {
            "type": "boolean",
            "nullable": true
          },
          "isHosting": {
            "type": "boolean",
            "nullable": true
          },
          "reverseDns": {
            "type": "string",
            "nullable": true
          },
          "confidence": {
            "type": "number",
            "format": "double",
            "nullable": true
          }
        },
        "additionalProperties": false
      },
      "GeoTimezoneDetail": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "nullable": true
          },
          "utcOffset": {
            "type": "string",
            "nullable": true
          },
          "offsetSeconds": {
            "type": "integer",
            "format": "int32"
          },
          "isDst": {
            "type": "boolean"
          },
          "currentLocalTime": {
            "type": "string",
            "nullable": true
          }
        },
        "additionalProperties": false
      },
      "GeocodingAccuracy": {
        "type": "object",
        "properties": {
          "type": {
            "type": "string",
            "description": "Accuracy type: \"rooftop\", \"parcel\", \"address_point\", \"interpolated\", \"centroid\", \"approximate\"",
            "nullable": true
          }
        },
        "additionalProperties": false,
        "description": "Geocoding accuracy classification"
      },
      "GeocodingAddressComponents": {
        "type": "object",
        "properties": {
          "streetNumber": {
            "type": "string",
            "nullable": true
          },
          "street": {
            "type": "string",
            "nullable": true
          },
          "unit": {
            "type": "string",
            "nullable": true
          },
          "city": {
            "type": "string",
            "nullable": true
          },
          "county": {
            "type": "string",
            "nullable": true
          },
          "countyFips": {
            "type": "string",
            "description": "5-digit county FIPS code",
            "nullable": true
          },
          "state": {
            "type": "string",
            "nullable": true
          },
          "zip": {
            "type": "string",
            "nullable": true
          },
          "zip4": {
            "type": "string",
            "nullable": true
          },
          "country": {
            "type": "string",
            "nullable": true
          }
        },
        "additionalProperties": false,
        "description": "Address components for geocoding result"
      },
      "GeocodingLocation": {
        "type": "object",
        "properties": {
          "latitude": {
            "type": "number",
            "format": "double"
          },
          "longitude": {
            "type": "number",
            "format": "double"
          }
        },
        "additionalProperties": false,
        "description": "Geographic coordinates"
      },
      "GeocodingResult": {
        "type": "object",
        "properties": {
          "inputAddress": {
            "type": "string",
            "description": "Original input address",
            "nullable": true
          },
          "formattedAddress": {
            "type": "string",
            "description": "Formatted/matched address",
            "nullable": true
          },
          "location": {
            "$ref": "#/components/schemas/GeocodingLocation"
          },
          "confidence": {
            "type": "number",
            "description": "Match confidence score (0.0 - 1.0)",
            "format": "double"
          },
          "accuracy": {
            "$ref": "#/components/schemas/GeocodingAccuracy"
          },
          "components": {
            "$ref": "#/components/schemas/GeocodingAddressComponents"
          },
          "interpolation": {
            "$ref": "#/components/schemas/InterpolationDetails"
          },
          "source": {
            "type": "string",
            "description": "Numeric match-quality code for this result (judge precision via the accuracy type + confidence).\r\nCodes: 10=primary, 11=exact/fast, 12=address point, 20=standardized, 30=extended-coverage, 40=interpolated, 41=nearest, 42=centroid.",
            "nullable": true
          },
          "sourceName": {
            "type": "string",
            "description": "The source code as a word: \"address_point\", \"primary\", \"interpolated\", \"zip_centroid\"...",
            "nullable": true,
            "readOnly": true
          },
          "addressId": {
            "type": "string",
            "description": "Stable id of the address point (usa_address_point.KeyHash, as text); only on address point answers.",
            "nullable": true
          },
          "timezone": {
            "$ref": "#/components/schemas/GeoTimezoneDetail"
          }
        },
        "additionalProperties": false,
        "description": "Response model for geocoding API (address to coordinates)"
      },
      "InterpolationDetails": {
        "type": "object",
        "properties": {
          "requestedHouseNumber": {
            "type": "integer",
            "description": "The house number that was requested",
            "format": "int32"
          },
          "lowerHouseNumber": {
            "type": "integer",
            "description": "Lower bracketing house number used for interpolation",
            "format": "int32",
            "nullable": true
          },
          "upperHouseNumber": {
            "type": "integer",
            "description": "Upper bracketing house number used for interpolation",
            "format": "int32",
            "nullable": true
          },
          "estimatedAccuracyMeters": {
            "type": "number",
            "description": "Estimated distance in meters from the interpolated point",
            "format": "double",
            "nullable": true
          }
        },
        "additionalProperties": false,
        "description": "Details about address interpolation when exact match not found"
      },
      "ProblemDetails": {
        "type": "object",
        "properties": {
          "type": {
            "type": "string",
            "nullable": true
          },
          "title": {
            "type": "string",
            "nullable": true
          },
          "status": {
            "type": "integer",
            "format": "int32",
            "nullable": true
          },
          "detail": {
            "type": "string",
            "nullable": true
          },
          "instance": {
            "type": "string",
            "nullable": true
          }
        },
        "additionalProperties": { }
      },
      "ReverseGeocodingResult": {
        "type": "object",
        "properties": {
          "location": {
            "$ref": "#/components/schemas/GeocodingLocation"
          },
          "formattedAddress": {
            "type": "string",
            "description": "Formatted address found",
            "nullable": true
          },
          "distance": {
            "type": "number",
            "description": "Distance from input coordinates to found address (in meters)",
            "format": "double"
          },
          "confidence": {
            "type": "number",
            "description": "Match confidence score (0.0 - 1.0). Derived from distance.",
            "format": "double"
          },
          "accuracy": {
            "$ref": "#/components/schemas/GeocodingAccuracy"
          },
          "components": {
            "$ref": "#/components/schemas/GeocodingAddressComponents"
          },
          "source": {
            "type": "string",
            "description": "Numeric match-quality code for this result (judge precision via the accuracy type + confidence).\r\nCodes: 10=primary, 11=exact/fast, 20=standardized, 30=extended-coverage, 40=interpolated, 41=nearest, 42=centroid.",
            "nullable": true
          },
          "sourceName": {
            "type": "string",
            "description": "The source code as a word: \"address_point\", \"exact_match\", \"extended_coverage\"...",
            "nullable": true,
            "readOnly": true
          },
          "addressId": {
            "type": "string",
            "description": "Stable id of the address point (usa_address_point.KeyHash, as text); only on address point answers.",
            "nullable": true
          },
          "timezone": {
            "$ref": "#/components/schemas/GeoTimezoneDetail"
          },
          "nearby": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ReverseGeocodingResult"
            },
            "description": "Other addresses near the coordinates, nearest first, one per building, each with its own location; only when limit is more than 1.",
            "nullable": true
          }
        },
        "additionalProperties": false,
        "description": "Response model for reverse geocoding API (coordinates to address)"
      },
      "V2MatchCodeBreakdown": {
        "type": "object",
        "properties": {
          "houseNumber": {
            "$ref": "#/components/schemas/V2MatchComponentCode"
          },
          "street": {
            "$ref": "#/components/schemas/V2MatchComponentCode"
          },
          "unit": {
            "$ref": "#/components/schemas/V2MatchComponentCode"
          },
          "city": {
            "$ref": "#/components/schemas/V2MatchComponentCode"
          },
          "state": {
            "$ref": "#/components/schemas/V2MatchComponentCode"
          },
          "zipCode": {
            "$ref": "#/components/schemas/V2MatchComponentCode"
          },
          "zip4": {
            "$ref": "#/components/schemas/V2MatchComponentCode"
          }
        },
        "additionalProperties": false
      },
      "V2MatchComponentCode": {
        "enum": [
          "NotApplicable",
          "Matched",
          "Corrected",
          "Inferred",
          "Unmatched"
        ],
        "type": "string"
      },
      "V2MatchMode": {
        "enum": [
          "Strict",
          "Balanced",
          "Fuzzy",
          "Speculative"
        ],
        "type": "string"
      },
      "V2MatchTier": {
        "enum": [
          "None",
          "Exact",
          "Near",
          "Approximate",
          "Speculative"
        ],
        "type": "string"
      },
      "V2ParsedAddressModel": {
        "type": "object",
        "properties": {
          "inputAddress": {
            "type": "string",
            "nullable": true
          },
          "fullAddressHash": {
            "type": "integer",
            "format": "int64"
          },
          "fullAddressHashString": {
            "type": "string",
            "nullable": true,
            "readOnly": true
          },
          "fullAddress": {
            "type": "string",
            "nullable": true
          },
          "addressLine1": {
            "type": "string",
            "nullable": true
          },
          "addressLine2": {
            "type": "string",
            "nullable": true
          },
          "addressNumber": {
            "type": "string",
            "nullable": true
          },
          "streetPreMod": {
            "type": "string",
            "nullable": true
          },
          "streetPreDir": {
            "type": "string",
            "nullable": true
          },
          "streetPreType": {
            "type": "string",
            "nullable": true
          },
          "streetPreSep": {
            "type": "string",
            "nullable": true
          },
          "streetName": {
            "type": "string",
            "nullable": true
          },
          "streetPostType": {
            "type": "string",
            "nullable": true
          },
          "streetPostDir": {
            "type": "string",
            "nullable": true
          },
          "streetPostMod": {
            "type": "string",
            "nullable": true
          },
          "unitType": {
            "type": "string",
            "nullable": true
          },
          "unitNumber": {
            "type": "string",
            "nullable": true
          },
          "city": {
            "type": "string",
            "nullable": true
          },
          "stateCode": {
            "type": "string",
            "nullable": true
          },
          "state": {
            "type": "string",
            "nullable": true
          },
          "zipCode": {
            "type": "string",
            "nullable": true
          },
          "zip4": {
            "type": "string",
            "nullable": true
          },
          "county": {
            "type": "string",
            "nullable": true
          },
          "matchMode": {
            "$ref": "#/components/schemas/V2MatchMode"
          },
          "matchTier": {
            "$ref": "#/components/schemas/V2MatchTier"
          },
          "confidence": {
            "type": "number",
            "format": "double"
          },
          "matchCode": {
            "$ref": "#/components/schemas/V2MatchCodeBreakdown"
          },
          "matchedFromCache": {
            "type": "boolean"
          },
          "footnotes": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "nullable": true
          },
          "isError": {
            "type": "boolean"
          },
          "errorMessages": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "nullable": true
          }
        },
        "additionalProperties": false
      },
      "V2VerifiedAddressModel": {
        "type": "object",
        "properties": {
          "inputAddress": {
            "type": "string",
            "nullable": true
          },
          "fullAddressHash": {
            "type": "integer",
            "format": "int64"
          },
          "fullAddressHashString": {
            "type": "string",
            "nullable": true,
            "readOnly": true
          },
          "fullAddress": {
            "type": "string",
            "nullable": true
          },
          "addressLine1": {
            "type": "string",
            "nullable": true
          },
          "addressLine2": {
            "type": "string",
            "nullable": true
          },
          "unitType": {
            "type": "string",
            "nullable": true
          },
          "unitNumber": {
            "type": "string",
            "nullable": true
          },
          "city": {
            "type": "string",
            "nullable": true
          },
          "stateCode": {
            "type": "string",
            "nullable": true
          },
          "county": {
            "type": "string",
            "nullable": true
          },
          "zipCode": {
            "type": "string",
            "nullable": true
          },
          "zip4": {
            "type": "string",
            "nullable": true
          },
          "carrierRoute": {
            "type": "string",
            "nullable": true
          },
          "deliveryPoint": {
            "type": "string",
            "nullable": true
          },
          "checkDigit": {
            "type": "string",
            "nullable": true
          },
          "cmar": {
            "type": "string",
            "nullable": true
          },
          "elot": {
            "type": "string",
            "nullable": true
          },
          "elotIndicator": {
            "type": "string",
            "nullable": true
          },
          "recordType": {
            "type": "string",
            "nullable": true
          },
          "dpvConfirmation": {
            "type": "string",
            "nullable": true
          },
          "defaultFlag": {
            "type": "string",
            "nullable": true
          },
          "defaultInd": {
            "type": "string",
            "nullable": true
          },
          "deliverableStatus": {
            "$ref": "#/components/schemas/DeliverableStatus"
          },
          "lastVerifiedDate": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "matchMode": {
            "$ref": "#/components/schemas/V2MatchMode"
          },
          "matchTier": {
            "$ref": "#/components/schemas/V2MatchTier"
          },
          "confidence": {
            "type": "number",
            "format": "double"
          },
          "matchCode": {
            "$ref": "#/components/schemas/V2MatchCodeBreakdown"
          },
          "matchedFromCache": {
            "type": "boolean"
          },
          "algorithmUsed": {
            "type": "string",
            "nullable": true
          },
          "footnotes": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "nullable": true
          },
          "isError": {
            "type": "boolean"
          },
          "errorMessages": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "nullable": true
          }
        },
        "additionalProperties": false
      }
    },
    "securitySchemes": {
      "Bearer": {
        "type": "http",
        "description": "Enter the JWT token obtained from GET /Auth/Token. Format: Bearer {token}",
        "scheme": "Bearer",
        "bearerFormat": "JWT"
      }
    }
  },
  "security": [
    {
      "Bearer": [ ]
    }
  ],
  "tags": [
    {
      "name": "Auth",
      "description": "Authenticate and obtain JWT tokens for API access"
    },
    {
      "name": "AutoCompleteUsa",
      "description": "Real-time address, city, and ZIP code autocomplete for USA"
    },
    {
      "name": "AutoCompleteIndia",
      "description": "Real-time city, locality, and PIN code autocomplete for India"
    },
    {
      "name": "AddressParserUsa",
      "description": "Parse freeform US addresses into structured components"
    },
    {
      "name": "AddressVerificationUsa",
      "description": "Verify US address deliverability with USPS DPV confirmation"
    },
    {
      "name": "GeocodingUsa",
      "description": "Forward and reverse geocoding for USA addresses"
    },
    {
      "name": "IpGeolocation",
      "description": "Locate an IPv4 or IPv6 address: country, region, city, coordinates, postal code, local time, flag and currency, plus the network behind it (ASN, ISP, mobile/proxy/hosting flags) and a confidence score"
    }
  ],
  "externalDocs": {
    "description": "Full API documentation with Try-It panels and code examples",
    "url": "https://sthan.io/docs"
  }
}