openapi: 3.0.3
info:
  title: Weather Source Location API
  description: |
    Geospatial metadata for latitude/longitude points, ZIP/Postal Codes, Designated Market Areas, and OnPoint™ points. The Weather Source Location API is built upon the [OnPoint™ Platform](https://weathersource.com/products/onpoint-platform/) which ensures data that is gap-free, homogeneous, and ready for immediate analysis. We offer the highest resolution grid on the market, covering every landmass in the world and up to 200 miles offshore.

    If you do not have a Weather Source API key [sign up for a free 30-day developer account](https://developer.weathersourceapis.com/account/sign-up/).
  termsOfService: https://weathersource.com/company/legal/terms-of-service/
  contact:
    name: Weather Source APIs
    url: https://developer.weathersourceapis.com/
    email: support@weathersource.com
  version: 2.0.0
servers:
- url: https://location.weathersourceapis.com/v2
security:
- ApiKeyAuth: []
tags:
- name: points
  description: Latitude/Longitude metadata
- name: postcodes
  description: Postcode metadata
- name: dmas
  description: Designated Market Area metadata
- name: onpoints
  description: OnPoint™ point metadata
paths:
  /points/{latitude},{longitude}:
    get:
      tags:
      - points
      summary: Latitude/Longitude geographical metadata
      description: Returns geographical metadata for a latitude/longitude point
      parameters:
      - name: latitude
        in: path
        description: A latitude value between -90° and 90°.
        required: true
        schema:
          maximum: 90.0
          minimum: -90.0
          type: number
          format: float
          example: 38.8552
      - name: longitude
        in: path
        description: A longitude value between -180° (West) and 180° (East).
        required: true
        schema:
          maximum: 180.0
          minimum: -180.0
          type: number
          format: float
          example: -77.0513
      responses:
        "200":
          description: Latitude/Longitude point geographical metadata response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/pointObj'
        default:
          description: Unexpected error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorObj'
  /postcodes/{postcode},{countryCode}:
    get:
      tags:
      - postcodes
      summary: Postcode geographical metadata
      description: Returns geographical metadata for a postcode
      parameters:
      - name: postcode
        in: path
        description: A postcode string.
        required: true
        schema:
          type: string
          example: "22222"
      - name: countryCode
        in: path
        description: An uppercase 2-character [ISO 3166-1 Alpha-2 country code](https://developer.weathersourceapis.com/apis/countries-with-postal-code-support/).
        required: true
        schema:
          pattern: ^([A-Z]){2}$
          type: string
          example: US
      responses:
        "200":
          description: Postcode geographical metadata response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/postcodeObj'
        default:
          description: Unexpected error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorObj'
  /dmas/{dmaId}:
    get:
      tags:
      - dmas
      summary: DMA geographical metadata
      description: Returns Designated Market Area geographical metadata
      parameters:
      - name: dmaId
        in: path
        description: A [Designated Market Area ID](https://developer.weathersourceapis.com/apis/supported-dmas/).
        required: true
        schema:
          type: integer
          example: 529
      responses:
        "200":
          description: Designated Market Area geographical metadata response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/dmaObj'
        default:
          description: Unexpected error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorObj'
  /onpoints/{onpointId}:
    get:
      tags:
      - onpoints
      summary: OnPoint™ point geographical metadata
      description: |
        Returns geographical metadata an OnPoint™ point.<br><br> Our patented OnPoint™ system uniquely identifies metadata for OnPoint™ IDs on the North America (5 km) and Global (22 km) grids. This resource is globally available, everywhere there is landmass (except Antartica).
      parameters:
      - name: onpointId
        in: path
        description: An OnPoint™ ID.
        required: true
        schema:
          type: integer
          example: 10725864
      responses:
        "200":
          description: OnPoint™ point geographical metadata response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/onpointObj'
        default:
          description: Unexpected error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorObj'
components:
  schemas:
    pointObj:
      required:
      - boundingPoints
      - grid
      - latitude
      - longitude
      - timezone
      type: object
      properties:
        latitude:
          $ref: '#/components/schemas/latitude'
        longitude:
          $ref: '#/components/schemas/longitude'
        timezone:
          $ref: '#/components/schemas/timezone'
        countryCode:
          $ref: '#/components/schemas/countryCode'
        countryName:
          $ref: '#/components/schemas/countryName'
        subdivCode:
          $ref: '#/components/schemas/subdivCode'
        subdivName:
          $ref: '#/components/schemas/subdivName'
        boundingPoints:
          $ref: '#/components/schemas/boundingPoints'
        grid:
          $ref: '#/components/schemas/grid'
      description: Metadata object for a postcode
    latitude:
      maximum: 90.0
      minimum: -90.0
      type: number
      description: A latitude value between -90° and 90°.
      format: float
      example: 38.8552
    longitude:
      maximum: 180.0
      minimum: -180.0
      type: number
      description: A longitude value between -180° (West) and 180° (East).
      format: float
      example: -77.0513
    timezone:
      type: string
      description: An Olson timezone ID.
      example: America/New_York
    countryCode:
      type: string
      description: An [ISO 3166-1 Alpha-2 country code](https://developer.weathersourceapis.com/apis/countries-with-postal-code-support/).
      example: US
    countryName:
      type: string
      description: A common country name.
      example: United States of America
    subdivCode:
      type: string
      description: An ISO 3166-2 country subdivision code.
      example: US-VA
    subdivName:
      type: string
      description: A common country subdivision name.
      example: Virginia
    boundingPoints:
      type: array
      description: A list of OnPoint™ points related to the location
      items:
        $ref: '#/components/schemas/boundingPoints_inner'
    onpointId:
      type: integer
      description: An OnPoint™ ID.
      example: 10725864
    grid:
      type: string
      description: The OnPoint™ grid on which the resource exists.
      example: NORTH_AMERICA_GRID
      enum:
      - GLOBAL_GRID
      - NORTH_AMERICA_GRID
    distance:
      type: number
      description: A distance from the provided point in miles.
      format: float
      example: 2.6772
    errorObj:
      type: object
      properties:
        errorCode:
          maximum: 600
          minimum: 100
          type: integer
          example: 404
        errorMessage:
          type: string
          example: NOT FOUND. Item not found.
    postcodeObj:
      required:
      - boundingPoints
      - countryCode
      - countryName
      - grid
      - latitude
      - latitude
      - longitude
      - postcode
      - timezone
      type: object
      properties:
        postcode:
          $ref: '#/components/schemas/postcode'
        latitude:
          $ref: '#/components/schemas/latitude'
        longitude:
          $ref: '#/components/schemas/longitude'
        timezone:
          $ref: '#/components/schemas/timezone'
        countryCode:
          $ref: '#/components/schemas/countryCode'
        countryName:
          $ref: '#/components/schemas/countryName'
        subdivCode:
          $ref: '#/components/schemas/subdivCode'
        subdivName:
          $ref: '#/components/schemas/subdivName'
        boundingPoints:
          $ref: '#/components/schemas/boundingPoints'
        grid:
          $ref: '#/components/schemas/grid'
      description: A postcode location metadata object
    postcode:
      type: string
      description: A postcode string.
      example: "22222"
    dmaObj:
      required:
      - countryCode
      - countryName
      - dmaId
      - dmaName
      - grid
      - population
      - samplePoints
      - timezone
      type: object
      properties:
        dmaId:
          $ref: '#/components/schemas/dmaId'
        dmaName:
          $ref: '#/components/schemas/dmaName'
        timezone:
          $ref: '#/components/schemas/timezone'
        population:
          $ref: '#/components/schemas/population'
        countryCode:
          $ref: '#/components/schemas/countryCode'
        countryName:
          $ref: '#/components/schemas/countryName'
        samplePoints:
          $ref: '#/components/schemas/samplePoints'
        grid:
          $ref: '#/components/schemas/grid'
      description: A Designated Market Area location metadata object
    dmaId:
      type: integer
      description: A [Designated Market Area ID](https://developer.weathersourceapis.com/apis/supported-dmas/).
      example: 529
    dmaName:
      type: string
      description: A Designated Market Area name.
      example: Louisville
    population:
      type: integer
      description: The population as represented in the 2010 census.
      example: 1584746
    samplePoints:
      type: array
      description: A list of OnPoint™ points used for interpolation for the Designated
        Market Area. These points are the OnPoint™ ID closest to the centroid of the
        10 most populous  postcodes within the target DMA.
      items:
        $ref: '#/components/schemas/samplePoints_inner'
    distancePop:
      type: integer
      description: The difference in population for the whole Designated Market Area
        and the population for the postcode represented by this sample point.
      example: 1536552
    onpointObj:
      required:
      - grid
      - latitude
      - longitude
      - onpointId
      - timezone
      type: object
      properties:
        onpointId:
          $ref: '#/components/schemas/onpointId'
        latitude:
          $ref: '#/components/schemas/latitude'
        longitude:
          $ref: '#/components/schemas/longitude'
        timezone:
          $ref: '#/components/schemas/timezone'
        countryCode:
          $ref: '#/components/schemas/countryCode'
        countryName:
          $ref: '#/components/schemas/countryName'
        subdivCode:
          $ref: '#/components/schemas/subdivCode'
        subdivName:
          $ref: '#/components/schemas/subdivName'
        grid:
          $ref: '#/components/schemas/grid'
      description: An OnPoint™ point location metadata object
    boundingPoints_inner:
      required:
      - distance
      - grid
      - latitude
      - longitude
      - onpointId
      type: object
      properties:
        onpointId:
          $ref: '#/components/schemas/onpointId'
        latitude:
          $ref: '#/components/schemas/latitude'
        longitude:
          $ref: '#/components/schemas/longitude'
        grid:
          $ref: '#/components/schemas/grid'
        distance:
          $ref: '#/components/schemas/distance'
    samplePoints_inner:
      required:
      - distance
      - grid
      - latitude
      - longitude
      - onpointId
      type: object
      properties:
        onpointId:
          $ref: '#/components/schemas/onpointId'
        latitude:
          $ref: '#/components/schemas/latitude'
        longitude:
          $ref: '#/components/schemas/longitude'
        grid:
          $ref: '#/components/schemas/grid'
        distance:
          $ref: '#/components/schemas/distancePop'
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      description: |-
        API key to authorize requests. If you do not have a Weather Source API key [sign up for a free 30-day developer account](https://developer.weathersourceapis.com/account/sign-up/).

        You can use the evaluation API Key `C0W60UOFRML47ytbXk4xlLBfv`. This evaluation API Key can only access the example locations found in this documentation.
      name: X-API-KEY
      in: header