> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ihuus.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Single Address Geocoding

> <Badge color="blue" icon="sparkles" size="lg" shape="pill">Pro AI</Badge>

Converts an address into geographic coordinates. This endpoint takes a free-text
location or address and returns the most likely latitude and longitude. It is designed
specifically for Agentic usage where only a single definitive location is needed.

To increase location accuracy, it is highly encouraged to provide as precise and
complete an address as possible. Providing an optional two-letter country code
(e.g., "us") is also strongly encouraged to increase accuracy. Returns null
coordinates and an explanatory message if no results are found.



## OpenAPI

````yaml /openapi.json get /tools/geocode-single
openapi: 3.1.0
info:
  title: Neighborhood Intelligence API
  description: >-
    High-performance geospatial API for neighborhood-level intelligence. Covers
    K-12 school search and four scored dimension groups: Vibe (privacy,
    walkability, visual appeal, dog friendliness, urban-rural character,
    liveliness), Environment (acoustic comfort, air quality, industrial
    proximity), Demographics (health insurance coverage, ideological lean,
    population age profile), and Risk (flood and fire hazard).
  contact:
    name: iHuus, Inc.
    url: https://ihuus.com/
  version: 0.1.0
servers:
  - url: https://api.ihuus.com/v1
    description: iHuus API v1
security:
  - BearerAuth: []
tags:
  - name: Schools & Ratings
    description: >-
      Search for K-12 schools by geographic coordinates. Results include
      distance, school level, district information, demographics, and
      performance metrics where available.
  - name: Vibe
    description: >-
      Neighborhood vibe dimension scores. Each endpoint returns a 0-255 score
      for a single dimension (privacy, walkability, visual appeal, dog
      friendliness, urban-rural character) along with a semantic description.
  - name: Environment
    description: >-
      Environment dimension scores (0-255). Includes composite noise levels, air
      quality, and other environmental factors accompanied by detailed source
      breakdowns.
  - name: Demographics
    description: >-
      Demographic dimension scores (0-255) derived from US Census Bureau data.
      Includes health insurance coverage and other population-level indicators.
  - name: Risk
    description: >-
      Risk dimension scores (0-255). Covers natural hazard exposure including
      flood and fire risk, derived from FEMA and other authoritative hazard
      datasets. Lower scores indicate higher risk.
  - name: Tools
    description: >-
      Auxiliary tools for processing data and agent assistance, such as
      geocoding addresses into geospatial coordinates.
paths:
  /tools/geocode-single:
    get:
      tags:
        - Tools
      summary: Single Address Geocoding
      description: >-
        <Badge color="blue" icon="sparkles" size="lg" shape="pill">Pro
        AI</Badge>


        Converts an address into geographic coordinates. This endpoint takes a
        free-text

        location or address and returns the most likely latitude and longitude.
        It is designed

        specifically for Agentic usage where only a single definitive location
        is needed.


        To increase location accuracy, it is highly encouraged to provide as
        precise and

        complete an address as possible. Providing an optional two-letter
        country code

        (e.g., "us") is also strongly encouraged to increase accuracy. Returns
        null

        coordinates and an explanatory message if no results are found.
      operationId: ihuus_tools_geocode_single
      parameters:
        - name: query
          in: query
          required: true
          schema:
            type: string
            title: Query
            description: >-
              The address or location query to geocode. e.g., '1600 Pennsylvania
              Ave NW, Washington, DC'
          description: >-
            The address or location query to geocode. e.g., '1600 Pennsylvania
            Ave NW, Washington, DC'
        - name: country
          in: query
          required: false
          schema:
            anyOf:
              - type: string
                minLength: 2
                maxLength: 2
              - type: 'null'
            title: Country
            description: >-
              Optional two-letter country code (ISO 3166-1 alpha-2) to improve
              geocoding accuracy.
          description: >-
            Optional two-letter country code (ISO 3166-1 alpha-2) to improve
            geocoding accuracy.
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeocodeSingleResponse'
        '401':
          description: Unauthorized — API key is missing, invalid, or expired.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
        '429':
          description: Too Many Requests — rate limit or monthly quota exceeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    GeocodeSingleResponse:
      properties:
        lat:
          anyOf:
            - type: number
            - type: 'null'
          title: Lat
          description: Latitude of the location. Null if no results found.
        lon:
          anyOf:
            - type: number
            - type: 'null'
          title: Lon
          description: Longitude of the location. Null if no results found.
        message:
          anyOf:
            - type: string
            - type: 'null'
          title: Message
          description: >-
            Additional information, such as error messages if no results were
            found.
      additionalProperties: false
      type: object
      title: GeocodeSingleResponse
      description: Response schema for single geocoding.
    ErrorResponse:
      type: object
      properties:
        detail:
          type: string
          description: Human-readable error message.
      required:
        - detail
      title: ErrorResponse
      description: >-
        Standard error response returned on authentication failure and
        rate-limit violations.
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: 'Your access token or API key. Pass as ``Authorization: Bearer <token>``.'

````