# `Localize.Territory.Hemisphere`
[🔗](https://github.com/elixir-localize/localize/blob/v1.4.0/lib/localize/territory/hemisphere.ex#L1)

Returns the hemisphere a territory lies in.

A season is the other half of the year either side of the equator, so
anything that writes or reckons seasons needs to know which hemisphere a
place is in. `hemisphere/1` answers for a territory code or for a locale,
whose territory it takes from `Localize.Territory.territory_from_locale/1`.

A territory the equator runs through has no single answer and is
`:ambiguous`: Brazil, Indonesia and Kenya each have summer in both halves
of the year depending where in them you stand.

## Where the data comes from

CLDR carries no latitude for a territory, so the classification here is the
library's own. Of the 261 territory codes CLDR knows, 154 own a zone in the
IANA time zone database and their hemisphere is checked against the
latitude it records (`test/localize/territory/hemisphere_test.exs`); the
rest share another territory's zone and carry no coordinate of their own.

A region (`:"002"`, `:"419"`) is not classified here at all. It is answered
from the territories it contains, so a region cannot disagree with its own
members: `:"005"` (South America) is `:ambiguous` because Brazil is, and
`:"053"` (Australasia) is `:southern` because everything in it is.

# `t`

```elixir
@type t() :: :northern | :southern | :ambiguous
```

The half of the world a territory lies in, or neither.

# `hemisphere`

```elixir
@spec hemisphere(Localize.LanguageTag.t() | atom() | String.t()) ::
  {:ok, t()} | {:error, Exception.t()}
```

Returns the hemisphere a territory lies in.

### Arguments

* `territory` is a territory code as an atom or a string, or a
  `t:Localize.LanguageTag.t/0` whose effective territory is used.

### Returns

* `{:ok, :northern}` for a territory above the equator.

* `{:ok, :southern}` for a territory below it.

* `{:ok, :ambiguous}` for a territory the equator runs through, and for a
  region holding territories on both sides of it.

* `{:error, exception}` if the territory is not known, or a locale names no
  territory.

### Examples

    iex> Localize.Territory.Hemisphere.hemisphere(:AU)
    {:ok, :southern}

    iex> Localize.Territory.Hemisphere.hemisphere("JP")
    {:ok, :northern}

    iex> Localize.Territory.Hemisphere.hemisphere(:BR)
    {:ok, :ambiguous}

    iex> {:ok, language_tag} = Localize.validate_locale("en-AU")
    iex> Localize.Territory.Hemisphere.hemisphere(language_tag)
    {:ok, :southern}

    iex> Localize.Territory.Hemisphere.hemisphere(:"053")
    {:ok, :southern}

    iex> Localize.Territory.Hemisphere.hemisphere(:"005")
    {:ok, :ambiguous}

# `hemisphere!`

```elixir
@spec hemisphere!(Localize.LanguageTag.t() | atom() | String.t()) :: t() | no_return()
```

Returns the hemisphere a territory lies in, raising on error.

### Arguments

* `territory` is a territory code as an atom or a string, or a
  `t:Localize.LanguageTag.t/0`. See `hemisphere/1`.

### Returns

* The hemisphere, one of `:northern`, `:southern` or `:ambiguous`.

### Raises

* Raises if the territory is not known, or a locale names no territory.

### Examples

    iex> Localize.Territory.Hemisphere.hemisphere!(:NZ)
    :southern

    iex> Localize.Territory.Hemisphere.hemisphere!(:FR)
    :northern

---

*Consult [api-reference.md](api-reference.md) for complete listing*