openapi: 3.1.0
info:
  title: Get State/Province Standard and Two-Letter Abbreviation API
  description: >
    This API standardizes state or province names and provides their two-letter abbreviations using AI-driven algorithms and knowledge bases.

    To use this API, you need an API key. Register for an API key at [Interzoid Registration](https://www.interzoid.com/register-api-account).

    For more information about this API, visit the [Interzoid State/Province Standardization API Documentation](https://www.interzoid.com/apis/standardize-state-province-data).

    You can also try this API [interactively](https://try.interzoid.com) or in high-speed [batch mode](https://batch.interzoid.com).
  version: 1.0.0
  contact:
    name: Interzoid Support
    url: https://www.interzoid.com
    email: support@interzoid.com
externalDocs:
  description: API home page and documentation
  url: https://www.interzoid.com/apis/standardize-state-province-data
servers:
  - url: https://api.interzoid.com
    description: Production server
tags:
  - name: State/Province Standardization
    description: Standardizes state or province names and provides two-letter abbreviations.
paths:
  /getstateabbreviation:
    get:
      operationId: getStateAbbreviation
      tags:
        - State/Province Standardization
      summary: Get Standardized State/Province Name and Abbreviation
      description: >
        Returns a standardized state or province name and its two-letter abbreviation based on the input. Include your API key (license) in the request. Register for an API key at https://www.interzoid.com/register-api-account.
      parameters:
        - name: license
          in: query
          required: true
          description: >
            Your API license key. Register for an API key at
            [Interzoid Registration](https://www.interzoid.com/register-api-account).
          schema:
            type: string
          examples:
            license:
              summary: API Key Example
              value: "dh8dj2f*****"
        - name: state
          in: query
          required: true
          description: The state or province name to standardize and abbreviate.
          schema:
            type: string
          examples:
            stateName:
              summary: State Name Example
              value: "Ohio"
        - name: algorithm
          in: query
          required: true
          description: The algorithm and AI model used to standardize the state or province name.
          schema:
            type: string
          examples:
            algorithm:
              summary: Algorithm Example
              value: "ai-medium"
      responses:
        '200':
          description: Successful response containing the standardized state name and abbreviation.
          content:
            application/json:
              schema:
                type: object
                properties:
                  State:
                    type: string
                    description: The standardized state or province name.
                  Abbreviation:
                    type: string
                    description: The two-letter abbreviation for the state or province.
                  Code:
                    type: string
                    description: Response code, "Success" if the call is successful.
                  Credits:
                    type: integer
                    description: Remaining credits for your API license.
              examples:
                success:
                  value:
                    State: "Ohio"
                    Abbreviation: "OH"
                    Code: "Success"
                    Credits: 10043
        '400':
          description: Bad request (e.g., missing or invalid parameters).
          content:
            text/plain:
              schema:
                type: string
              examples:
                error:
                  value: "Invalid license key or state name missing."
        '402':
          description: API key not found.
          content:
            text/plain:
              schema:
                type: string
              examples:
                error:
                  value: "API key not found."
        '403':
          description: Insufficient API credits remaining.
          content:
            text/plain:
              schema:
                type: string
              examples:
                error:
                  value: "Insufficient API credits remaining."
        '405':
          description: Method not allowed.
          content:
            text/plain:
              schema:
                type: string
              examples:
                error:
                  value: "Method not allowed."
        '429':
          description: Rate limits reached.
          content:
            text/plain:
              schema:
                type: string
              examples:
                error:
                  value: "Rate limits reached."
        '500':
          description: Internal server error.
          content:
            text/plain:
              schema:
                type: string
              examples:
                error:
                  value: "Internal server error."
components:
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      name: license
      in: query
  schemas: {}
security:
  - apiKeyAuth: []