# AwsRegions

A simple Elixir library providing a list of all AWS regions with their names, geography, and continent data.

Based on the [official AWS documentation](https://docs.aws.amazon.com/global-infrastructure/latest/regions/aws-regions.html).

## Installation

Add `aws_regions` to your list of dependencies in `mix.exs`:

```elixir
def deps do
  [
    {:aws_regions, "~> 0.1.0"}
  ]
end
```

## Functions

| Function | Description | Return Type |
|---|---|---|
| `AwsRegions.list(opts)` | Returns all 34 AWS regions | `[%{code, name, geography, continent}]` |
| `AwsRegions.codes()` | Returns all region codes | `["us-east-1", "us-east-2", ...]` |
| `AwsRegions.names()` | Returns all region names (English) | `["US East (N. Virginia)", ...]` |
| `AwsRegions.get(code, opts)` | Looks up a region by code | `{:ok, region}` or `:error` |
| `AwsRegions.count()` | Returns the total number of regions | `34` |
| `AwsRegions.continents()` | Returns all continent groupings | `["Africa", "Asia Pacific", ...]` |
| `AwsRegions.by_continent(name, opts)` | Returns all regions in a continent | `[%{code, name, geography, continent}]` |
| `AwsRegions.group_by_continent(opts)` | Returns all regions grouped by continent | `[{"Africa", [regions]}, ...]` |
| `AwsRegions.supported_languages()` | Returns all supported language codes | `["en", "zh"]` |

Functions that accept `opts` support `lang: "xx"` for translated output. Unsupported languages return `{:error, :unsupported_language}`.

## Region Data Structure

Each region is a map with the following keys:

```elixir
%{
  code: "us-east-1",
  name: "US East (N. Virginia)",
  geography: "United States of America",
  continent: "North America"
}
```

## Usage Examples

```elixir
# List all regions
AwsRegions.list()
# => [%{code: "us-east-1", name: "US East (N. Virginia)", geography: "United States of America", continent: "North America"}, ...]

# Get all region codes
AwsRegions.codes()
# => ["us-east-1", "us-east-2", "us-west-1", ...]

# Get all region names
AwsRegions.names()
# => ["US East (N. Virginia)", "US East (Ohio)", ...]

# Look up a specific region
AwsRegions.get("eu-west-1")
# => {:ok, %{code: "eu-west-1", name: "Europe (Ireland)", geography: "Ireland", continent: "Europe"}}

AwsRegions.get("invalid")
# => :error

# Filter by continent
AwsRegions.by_continent("Europe")
# => [%{code: "eu-central-1", name: "Europe (Frankfurt)", geography: "Germany", continent: "Europe"}, ...]

# List all continents
AwsRegions.continents()
# => ["Africa", "Asia Pacific", "Europe", "Middle East", "North America", "South America"]

# Group all regions by continent
AwsRegions.group_by_continent()
# => [
#   {"Africa", [%{code: "af-south-1", ...}]},
#   {"Asia Pacific", [%{code: "ap-south-1", ...}, ...]},
#   {"Europe", [%{code: "eu-central-1", ...}, ...]},
#   {"Middle East", [...]},
#   {"North America", [...]},
#   {"South America", [...]}
# ]

# Get region count
AwsRegions.count()
# => 34
```

## Translation Support

By default all functions return English data. Pass `lang: "xx"` to get translated region names and geography. Region codes and continent keys always stay in English.

| Code | Language   |
|------|------------|
| `en` | English (default) |
| `ar` | Arabic     |
| `de` | German     |
| `es` | Spanish    |
| `et` | Estonian   |
| `fr` | French     |
| `hi` | Hindi      |
| `ja` | Japanese   |
| `pt` | Portuguese |
| `ru` | Russian    |
| `zh` | Chinese    |

```elixir
# Check supported languages
AwsRegions.supported_languages()
# => ["ar", "de", "en", "es", "fr", "hi", "ja", "pt", "ru", "zh"]

# List regions in Japanese
AwsRegions.list(lang: "ja")
# => [%{code: "us-east-1", name: "米国東部（バージニア北部）", geography: "アメリカ合衆国", continent: "North America"}, ...]

# Look up a region in French
AwsRegions.get("eu-west-1", lang: "fr")
# => {:ok, %{code: "eu-west-1", name: "Europe (Irlande)", geography: "Irlande", continent: "Europe"}}

# Filter by continent in Spanish
AwsRegions.by_continent("Europe", lang: "es")
# => [%{code: "eu-central-1", name: "Europa (Fráncfort)", geography: "Alemania", continent: "Europe"}, ...]

# Group by continent in German
AwsRegions.group_by_continent(lang: "de")
# => [{"Africa", [%{code: "af-south-1", name: "Afrika (Kapstadt)", ...}]}, ...]

# Unsupported language
AwsRegions.list(lang: "xx")
# => {:error, :unsupported_language}
```

## Documentation

Full docs are available at [HexDocs](https://hexdocs.pm/aws_regions).