Gridsquare
View SourceGridSquare 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.1.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: "DN40BI00OR", 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 (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: "DN40BI00OR12", subsquare: "dn40bi"}
# Decode back to coordinates
precise_location = Gridsquare.decode("DN40BI00OR12")
# Returns %Gridsquare.DecodeResult{} with much higher precision
Contributing
- Fork it
- Create your feature branch (
git checkout -b feature/my-new-feature
) - Commit your changes (
git commit -am 'Add some feature'
) - Push to the branch (
git push origin feature/my-new-feature
) - 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.