{
  "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": {
    "/addressparser/usa/single/{address}": {
      "get": {
        "tags": [
          "AddressParserUsa"
        ],
        "summary": "Parse a freeform US address into structured components (street, city, state, ZIP, etc.).",
        "parameters": [
          {
            "name": "address",
            "in": "path",
            "description": "The freeform address string to parse (URL-encoded).",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Returns the parsed address components.",
            "content": {
              "text/plain": {
                "schema": {
                  "$ref": "#/components/schemas/ParsedAddressModel"
                }
              },
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ParsedAddressModel"
                }
              },
              "text/json": {
                "schema": {
                  "$ref": "#/components/schemas/ParsedAddressModel"
                }
              }
            }
          },
          "400": {
            "description": "Address parameter is missing or empty."
          },
          "404": {
            "description": "Address could not be parsed."
          },
          "429": {
            "description": "Rate limit exceeded."
          },
          "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": {
          "Confidence >= 0.95": "Exact match — all parsed components are highly reliable",
          "Confidence 0.85-0.94": "High confidence — minor normalization applied, components are reliable",
          "Confidence 0.70-0.84": "Medium confidence — some components may have been inferred or corrected, present to user for confirmation",
          "Confidence < 0.70": "Low confidence — significant uncertainty, ask the user to verify the parsed result",
          "IsPostalVerified = true": "Components were validated against postal data",
          "IsPostalVerified = false": "Parsed from input only — not cross-checked against postal records"
        },
        "x-ai-next-actions": {
          "Confidence >= 0.85": "Use the parsed components directly. If deliverability is needed, call Address Verification with the FullAddress.",
          "Confidence < 0.70": "Present the parsed result to the user and ask them to confirm before using it downstream."
        }
      }
    },
    "/addressverification/usa/single/{address}": {
      "get": {
        "tags": [
          "AddressVerificationUsa"
        ],
        "summary": "Verify a US address for deliverability using USPS DPV confirmation.",
        "parameters": [
          {
            "name": "address",
            "in": "path",
            "description": "The address string to verify (URL-encoded).",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Returns the verified address with DPV confirmation.",
            "content": {
              "text/plain": {
                "schema": {
                  "$ref": "#/components/schemas/VerifiedAddressModel"
                }
              },
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/VerifiedAddressModel"
                }
              },
              "text/json": {
                "schema": {
                  "$ref": "#/components/schemas/VerifiedAddressModel"
                }
              }
            }
          },
          "400": {
            "description": "Address parameter is missing or empty."
          },
          "404": {
            "description": "Address could not be verified."
          },
          "429": {
            "description": "Rate limit exceeded."
          },
          "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": {
          "DpvConfirmation = Y": "Address confirmed — it is a valid, deliverable postal address",
          "DpvConfirmation = N": "Not confirmed — address was not found in postal data, likely does not exist",
          "DpvConfirmation = S": "Street address is valid but missing apartment/suite/unit number — ask the user for the unit",
          "DpvConfirmation = D": "Street address confirmed but the specific unit could not be verified",
          "IsPostalVerified = true": "Address was matched against authoritative postal data",
          "IsPostalVerified = false": "Address could not be verified — treat with caution",
          "RecordType = H": "Highrise (apartment building)",
          "RecordType = S": "Street address (individual house)",
          "RecordType = F": "Firm/business address",
          "RecordType = P": "PO Box"
        },
        "x-ai-next-actions": {
          "DpvConfirmation = S": "Ask the user: 'What is the apartment or unit number?' Then re-verify with the unit included.",
          "DpvConfirmation = Y, need coordinates": "Call Forward Geocoding with the verified FullAddress to get lat/long.",
          "DpvConfirmation = N": "Tell the user the address could not be verified. Suggest they double-check spelling, city, state, and ZIP."
        }
      }
    },
    "/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": "The display type.",
            "required": true,
            "schema": {
              "type": "integer",
              "format": "int32"
            }
          }
        ],
        "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": "The display type.",
            "required": true,
            "schema": {
              "type": "integer",
              "format": "int32"
            }
          }
        ],
        "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": "The display type.",
            "required": true,
            "schema": {
              "type": "integer",
              "format": "int32"
            }
          }
        ],
        "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": "The display type for the results (0 for StateCode, 1 for State).",
            "required": true,
            "schema": {
              "type": "integer",
              "format": "int32",
              "default": 0
            }
          }
        ],
        "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": "The display type for the results:\r\n<list type=\"bullet\"><item><description>0 - ZipCode, City, StateCode</description></item><item><description>1 - ZipCode, City, State</description></item><item><description>2 - ZipCode-Zip4, City, StateCode</description></item><item><description>3 - ZipCode-Zip4, City, State</description></item></list>",
            "required": true,
            "schema": {
              "type": "integer",
              "format": "int32",
              "default": 0
            }
          }
        ],
        "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"
            }
          }
        ],
        "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 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"
        },
        "x-ai-notes": "IP Geolocation uses PascalCase field names (IpAddress, Country, CountryCode, Region, City, Latitude, Longitude, Continent, Timezone, PostalCode)."
      }
    }
  },
  "components": {
    "schemas": {
      "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
          }
        },
        "additionalProperties": false
      },
      "GeocodingAccuracy": {
        "type": "object",
        "properties": {
          "type": {
            "type": "string",
            "description": "Accuracy type: \"rooftop\", \"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
          },
          "city": {
            "type": "string",
            "nullable": true
          },
          "county": {
            "type": "string",
            "nullable": true
          },
          "state": {
            "type": "string",
            "nullable": true
          },
          "zip": {
            "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 source code indicating which geocoding source produced this result.\r\nCodes: 10=primary, 11=fast-match, 20=census, 30=external, 40=interpolated, 41=nearest, 42=centroid.",
            "nullable": true
          }
        },
        "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"
      },
      "ParsedAddressModel": {
        "type": "object",
        "properties": {
          "inputAddress": {
            "type": "string",
            "nullable": true
          },
          "fullAddressHash": {
            "type": "integer",
            "format": "int64"
          },
          "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
          },
          "isPostalVerified": {
            "type": "boolean"
          },
          "algorithmUsed": {
            "type": "string",
            "nullable": true
          },
          "confidence": {
            "type": "number",
            "format": "double"
          },
          "isError": {
            "type": "boolean"
          },
          "errorMessages": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "nullable": true
          }
        },
        "additionalProperties": false
      },
      "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 source code indicating which geocoding source produced this result.\r\nCodes: 10=primary, 11=fast-match, 20=census, 30=external, 40=interpolated, 41=nearest, 42=centroid.",
            "nullable": true
          }
        },
        "additionalProperties": false,
        "description": "Response model for reverse geocoding API (coordinates to address)"
      },
      "VerifiedAddressModel": {
        "type": "object",
        "properties": {
          "inputAddress": {
            "type": "string",
            "nullable": true
          },
          "fullAddressHash": {
            "type": "integer",
            "format": "int64"
          },
          "fullAddress": {
            "type": "string",
            "nullable": true
          },
          "addressLine1": {
            "type": "string",
            "nullable": true
          },
          "addressLine2": {
            "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
          },
          "algorithmUsed": {
            "type": "string",
            "nullable": true
          },
          "isPostalVerified": {
            "type": "boolean"
          },
          "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": "Lookup geolocation data (country, region, city, coordinates) from IP addresses"
    }
  ],
  "externalDocs": {
    "description": "Full API documentation with Try-It panels and code examples",
    "url": "https://sthan.io/docs"
  }
}