ExOwm.Location (ExOwm v2.0.0)

Validated location types for OpenWeatherMap API requests.

This module provides constructors for creating validated location structs that can be used with ExOwm API functions.

Examples

iex> ExOwm.Location.by_city("Warsaw")
%ExOwm.Location{type: :city, city: "Warsaw", country: nil}

iex> ExOwm.Location.by_coords(52.374031, 4.88969)
%ExOwm.Location{type: :coords, lat: 52.374031, lon: 4.88969}

iex> ExOwm.Location.by_id(2759794)
%ExOwm.Location{type: :id, id: 2759794}

iex> ExOwm.Location.by_zip("94040", country: "us")
%ExOwm.Location{type: :zip, zip: "94040", country: "us"}

Summary

Types

t()

Functions

by_city(city, opts \\ [])

Creates a location by city name.

by_coords(lat, lon)

Creates a location by geographic coordinates.

by_id(id)

Creates a location by OpenWeatherMap city ID.

by_zip(zip, opts)

Creates a location by ZIP/postal code.

with_timestamp(location, timestamp)

Adds a timestamp to a location (for historical weather queries).

Types

t()

@type t() :: %ExOwm.Location{
  city: String.t() | nil,
  country: String.t() | nil,
  dt: pos_integer() | nil,
  id: pos_integer() | nil,
  lat: float() | nil,
  lon: float() | nil,
  query: String.t() | nil,
  type: :city | :coords | :id | :zip | :geocode_query,
  zip: String.t() | nil
}

Functions

by_city(city, opts \\ [])

@spec by_city(
  String.t(),
  keyword()
) :: t()

Creates a location by city name.

Options

:country - ISO 3166 country code (e.g., "us", "pl", "uk")

Examples

iex> ExOwm.Location.by_city("Warsaw")
%ExOwm.Location{type: :city, city: "Warsaw", country: nil}

iex> ExOwm.Location.by_city("London", country: "uk")
%ExOwm.Location{type: :city, city: "London", country: "uk"}

by_coords(lat, lon)

@spec by_coords(float(), float()) :: t()

Creates a location by geographic coordinates.

Parameters

lat - Latitude (-90 to 90)
lon - Longitude (-180 to 180)

Examples

iex> ExOwm.Location.by_coords(52.374031, 4.88969)
%ExOwm.Location{type: :coords, lat: 52.374031, lon: 4.88969}

by_id(id)

@spec by_id(pos_integer()) :: t()

Creates a location by OpenWeatherMap city ID.

Examples

iex> ExOwm.Location.by_id(2759794)
%ExOwm.Location{type: :id, id: 2759794}

by_zip(zip, opts)

@spec by_zip(
  String.t(),
  keyword()
) :: t()

Creates a location by ZIP/postal code.

Options

:country - ISO 3166 country code (required)

Examples

iex> ExOwm.Location.by_zip("94040", country: "us")
%ExOwm.Location{type: :zip, zip: "94040", country: "us"}

with_timestamp(location, timestamp)

@spec with_timestamp(t(), pos_integer()) :: t()

Adds a timestamp to a location (for historical weather queries).

Parameters

location - An existing location struct
timestamp - Unix timestamp

Examples

iex> location = ExOwm.Location.by_coords(52.374031, 4.88969)
iex> ExOwm.Location.with_timestamp(location, 1615546800)
%ExOwm.Location{type: :coords, lat: 52.374031, lon: 4.88969, dt: 1615546800}