Gridsquare

GridSquare calculator for encoding/decoding between latitude/longitude and Maidenhead Locator System grid references.

The Maidenhead Locator System is used by ham radio operators to exchange approximate locations. It uses a base conversion system with changing radix:

• First pair: base 18 (A-R) for 10° lat × 20° lon fields
• Second pair: base 10 (0-9) for 1° lat × 2° lon squares
• Third pair: base 24 (A-X) for 2.5' lat × 5' lon subsquares
• Fourth pair: base 10 (0-9) for extended subsquares
• Can be extended indefinitely with alternating base 10/base 24 pairs

Installation

The package can be installed by adding gridsquare to your list of dependencies in mix.exs:

def deps do
  [
    {:gridsquare, "~> 0.3.0"}
  ]
end

Usage

Encoding coordinates to grid square

# Basic encoding (6-character precision)
Gridsquare.encode(-111.866785, 40.363840)
# Returns: %Gridsquare.EncodeResult{grid_reference: "DN40bi", subsquare: "dn40bi"}

# Extended precision (10-character precision)
Gridsquare.encode(-111.866785, 40.363840, 10)
# Returns: %Gridsquare.EncodeResult{grid_reference: "DN40BI57XH", subsquare: "dn40bi"}

Decoding grid square to coordinates

Gridsquare.decode("DN40bi")
# Returns: %Gridsquare.DecodeResult{
#   latitude: 40.35416666666667,
#   longitude: -111.875,
#   width: 0.08333333333333333,
#   height: 0.041666666666666664
# }

Creating a GridSquare struct

grid = Gridsquare.new("DN40bi")
# Returns: %Gridsquare.GridSquare{
#   grid_reference: "DN40bi",
#   center: %{latitude: 40.35416666666667, longitude: -111.875},
#   width: 0.08333333333333333,
#   height: 0.041666666666666664
# }

# Access the center coordinates
grid.center.latitude   # 40.35416666666667
grid.center.longitude  # -111.875

# Access the dimensions
grid.width   # 0.08333333333333333 (5 minutes)
grid.height  # 0.041666666666666664 (2.5 minutes)

API Reference

Gridsquare.encode(longitude, latitude, precision \\ 6)

Encodes latitude and longitude coordinates to a Maidenhead grid square reference.

Parameters:

• longitude (float): Longitude coordinate (-180 to 180)
• latitude (float): Latitude coordinate (-90 to 90)
• precision (integer): Number of characters in the grid reference (even values 6 to 20, default: 6)

Returns:%Gridsquare.EncodeResult{grid_reference: String.t(), subsquare: String.t()}

Gridsquare.decode(grid_reference)

Decodes a Maidenhead grid square reference to latitude and longitude coordinates.

Parameters:

• grid_reference (String.t()): The grid square reference to decode

Returns:%Gridsquare.DecodeResult{latitude: float(), longitude: float(), width: float(), height: float()}

Gridsquare.new(grid_reference)

Creates a GridSquare struct from a grid reference.

Parameters:

• grid_reference (String.t()): The grid square reference

Returns:%Gridsquare.GridSquare{grid_reference: String.t(), center: %{latitude: float(), longitude: float()}, width: float(), height: float()}

Precision Levels

The precision parameter controls how many characters are in the resulting grid reference:

• 6 characters (default): Field + Square + Subsquare (2.5' × 5' precision)
• 8 characters: Adds first extended pair (base 10)
• 10 characters: Adds second extended pair (base 24)
• 12 characters: Adds third extended pair (base 10)
• And so on...

Each additional pair increases precision by approximately 10x.

Examples

# High precision encoding for precise location
precise_grid = Gridsquare.encode(-111.866785, 40.363840, 12)
# %Gridsquare.EncodeResult{grid_reference: "DN40BI57XH67", subsquare: "dn40bi"}

# Decode back to coordinates with progressively smaller grid dimensions
precise_location = Gridsquare.decode("DN40BI57XH67")
# Returns %Gridsquare.DecodeResult{} with higher precision width/height

Contributing

1. Fork it
2. Create your feature branch (git checkout -b feature/my-new-feature)
3. Commit your changes (git commit -am 'Add some feature')
4. Push to the branch (git push origin feature/my-new-feature)
5. Create new Pull Request

License

This project is licensed under the GPLv2 License - see the LICENSE file for details.

Documentation

Documentation can be generated with ExDoc and published on HexDocs. Once published, the docs can be found at https://hexdocs.pm/gridsquare.