openapi: 3.1.0
info:
  title: Interzoid Standardize City Data API
  description: >
    This API standardizes a given city name worldwide using specialized algorithms and AI models, ensuring consistent and normalized city data for improved data accuracy and processing.

    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 Standardize City Data API Documentation](https://www.interzoid.com/apis/standardize-city-data).
  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-city-data
servers:
  - url: https://api.interzoid.com
    description: Production server
tags:
  - name: City Data Standardization
    description: Standardizes city names for consistent and normalized data.
paths:
  /getcitystandard:
    get:
      tags:
        - City Data Standardization
      summary: Standardize City Name
      description: >
        This method standardizes a given city name worldwide using specialized algorithms and AI models, returning a normalized and consistent version.

        **Note**: You must include your API key as the `license` parameter in the request. If you do not have an API key, you can register for one at [Interzoid Registration](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: "r2d7df664a7c4ef6h8k"
        - name: city
          in: query
          required: true
          description: The global city name to be standardized
          schema:
            type: string
          examples:
            city:
                summary: Global City Name Example
                value: "San Fran."
        - name: algorithm
          in: query
          required: true
          description: The standardization algorithm and AI model used to standardize the city name.
          schema:
            type: string
          examples:
            algorithm:
                summary: Algorithm Example
                value: "ai-medium"
      responses:
        '200':
          description: Successful response containing the standardized city data.
          content:
            application/json:
              schema:
                type: object
                properties:
                  CityNameStandard:
                    type: string
                    description: The standardized city name.
                  Credits:
                    type: integer
                    description: Remaining credits for your API license.
                  Code:
                    type: string
                    description: Execution status message.
                examples:
                  - summary: Successful response example
                    value:
                      CityNameStandard: "San Francisco"
                      Credits: 4999
                      Code: "Success"
        '400':
          description: Bad request (e.g., missing or invalid parameters).
          content:
            application/json:
              schema:
                type: object
                properties:
                  Code:
                    type: integer
                    description: Response code.
                  Message:
                    type: string
                    description: Error message.
                examples:
                  - summary: Missing or invalid parameters
                    value:
                      Code: 400
                      Message: "Invalid license key or city parameter missing."
        '402':
          description: API key not found.
          content:
            application/json:
              schema:
                type: object
                properties:
                  Code:
                    type: integer
                    description: Response code.
                  Message:
                    type: string
                    description: Error message.
                examples:
                  - summary: API key not found
                    value:
                      Code: 402
                      Message: "API key not found."
        '403':
          description: Insufficient API credits remaining.
          content:
            application/json:
              schema:
                type: object
                properties:
                  Code:
                    type: integer
                    description: Response code.
                  Message:
                    type: string
                    description: Error message.
                examples:
                  - summary: Insufficient credits
                    value:
                      Code: 403
                      Message: "Insufficient API credits remaining."
        '405':
          description: Method not allowed.
          content:
            application/json:
              schema:
                type: object
                properties:
                  Code:
                    type: integer
                    description: Response code.
                  Message:
                    type: string
                    description: Error message.
                examples:
                  - summary: Wrong HTTP method
                    value:
                      Code: 405
                      Message: "Method not allowed."
        '429':
          description: Rate limits reached.
          content:
            application/json:
              schema:
                type: object
                properties:
                  Code:
                    type: integer
                    description: Response code.
                  Message:
                    type: string
                    description: Error message.
                examples:
                  - summary: Rate limit reached
                    value:
                      Code: 429
                      Message: "Rate limits reached."
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                type: object
                properties:
                  Code:
                    type: integer
                    description: Response code.
                  Message:
                    type: string
                    description: Error message.
                examples:
                  - summary: Server error
                    value:
                      Code: 500
                      Message: "Internal server error."
components:
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      name: license
      in: query
  schemas:
    ResponseError:
      type: object
      properties:
        Code:
          type: integer
          description: Response code.
        Message:
          type: string
          description: Error message.
security:
  - apiKeyAuth: []