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.
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