OpenWeatherMap Geocoding API

openapi: 3.2.0
info:
  title: OpenWeatherMap Geocoding API
  version: 1.0.0
  description: Direct and reverse geocoding for city names, zip codes, and coordinate pairs. Supports city, state, country, and area-level resolution and is used to convert between location text and geographic coordinates.
  contact:
    name: OpenWeather
    url: https://openweathermap.org/api/geocoding-api
  license:
    name: Creative Commons Attribution-ShareAlike 4.0 International
    url: https://creativecommons.org/licenses/by-sa/4.0/
servers:
- url: https://api.openweathermap.org/geo/1.0
  description: Geocoding API base URL
security:
- appid: []
tags:
- name: Geocoding
  description: Direct and reverse geocoding between location names and coordinates.
paths:
  /direct:
    get:
      operationId: getDirectGeocoding
      summary: Direct Geocoding By Location Name
      description: Returns geographic coordinates for a location specified by city name, optional state code (US only), and optional ISO 3166 country code.
      tags:
      - Geocoding
      parameters:
      - name: q
        in: query
        required: true
        description: City name, optional state and country codes, comma-separated.
        schema:
          type: string
      - name: limit
        in: query
        required: false
        description: Maximum number of locations to return. Up to 5.
        schema:
          type: integer
          minimum: 1
          maximum: 5
      - $ref: '#/components/parameters/Appid'
      responses:
        '200':
          description: Direct geocoding response.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/GeocodingResult'
        '400':
          description: Invalid request parameters.
        '401':
          description: Unauthorized.
        '429':
          description: Too many requests.
  /zip:
    get:
      operationId: getZipGeocoding
      summary: Direct Geocoding By Zip Or Post Code
      description: Returns the coordinates for a zip or postal code, requires a country code suffix.
      tags:
      - Geocoding
      parameters:
      - name: zip
        in: query
        required: true
        description: Zip code and country code, comma-separated.
        schema:
          type: string
      - $ref: '#/components/parameters/Appid'
      responses:
        '200':
          description: Zip geocoding response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ZipGeocodingResult'
        '400':
          description: Invalid request parameters.
        '401':
          description: Unauthorized.
        '429':
          description: Too many requests.
  /reverse:
    get:
      operationId: getReverseGeocoding
      summary: Reverse Geocoding By Coordinate
      description: Returns the location name or names associated with the supplied latitude and longitude.
      tags:
      - Geocoding
      parameters:
      - name: lat
        in: query
        required: true
        description: Latitude in decimal degrees.
        schema:
          type: number
          format: float
      - name: lon
        in: query
        required: true
        description: Longitude in decimal degrees.
        schema:
          type: number
          format: float
      - name: limit
        in: query
        required: false
        description: Maximum number of locations to return.
        schema:
          type: integer
      - $ref: '#/components/parameters/Appid'
      responses:
        '200':
          description: Reverse geocoding response.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/GeocodingResult'
        '400':
          description: Invalid request parameters.
        '401':
          description: Unauthorized.
        '429':
          description: Too many requests.
components:
  parameters:
    Appid:
      name: appid
      in: query
      required: true
      description: OpenWeather API key.
      schema:
        type: string
  schemas:
    GeocodingResult:
      type: object
      properties:
        name:
          type: string
        local_names:
          type: object
          additionalProperties:
            type: string
        lat:
          type: number
          format: float
        lon:
          type: number
          format: float
        country:
          type: string
        state:
          type: string
    ZipGeocodingResult:
      type: object
      properties:
        zip:
          type: string
        name:
          type: string
        lat:
          type: number
          format: float
        lon:
          type: number
          format: float
        country:
          type: string
  securitySchemes:
    appid:
      type: apiKey
      in: query
      name: appid