Geolixir (geolixir v0.1.1)
View SourceGeolixir provides a simple and unified interface for geocoding and reverse geocoding using various external providers.
It allows converting addresses to geographical coordinates (latitude and longitude) and vice-versa.
Usage
Add Geolixir to your mix.exs
dependencies:
def deps do
[
{:geolixir, "~> 0.1.1"}
]
end
Then fetch the dependencies:
mix deps.get
Geocoding
# Using the default provider (OpenStreetMap)
iex> Geolixir.geocode("1600 Amphitheatre Parkway, Mountain View, CA")
{:ok, %Geolixir.Result{
coordinates: %Geolixir.Coords{lat: 37.4224764, lon: -122.0842499},
location: %Geolixir.Location{...},
...
}}
# Using a specific provider (e.g., Geoapify, requires API key)
iex> Geolixir.geocode("Eiffel Tower, Paris", provider: :geoapify, api_key: "YOUR_GEOAPIFY_KEY")
{:ok, %Geolixir.Result{...}}
Reverse Geocoding
# Using the default provider
iex> Geolixir.reverse_geocode(48.8584, 2.2945)
{:ok, %Geolixir.Result{
location: %Geolixir.Location{formatted_address: "Tour Eiffel, 5, Avenue Anatole France, ...", ...},
...
}}
# Using a specific provider (e.g., PositionStack, requires API key)
iex> Geolixir.reverse_geocode(40.7128, -74.0060, provider: :position_stack, api_key: "YOUR_POSITIONSTACK_KEY")
{:ok, %Geolixir.Result{...}}
See geocode/2
and reverse_geocode/3
for more details and options.
Summary
Functions
Geocodes a given address string into geographical coordinates.
Reverse geocodes geographical coordinates (latitude and longitude) into an address.
Functions
@spec geocode( String.t(), keyword() ) :: {:ok, Geolixir.Result.t()} | {:error, atom() | map()}
Geocodes a given address string into geographical coordinates.
It uses the configured default provider unless a specific :provider
is
specified in the options. Some providers may require an :api_key
.
Parameters
address
: The address string to geocode (e.g., "1600 Amphitheatre Parkway, Mountain View, CA").opts
: A keyword list of options.:provider
: (Optional) The atom representing the provider module to use (e.g.,:geoapify
,:open_street_maps
). Defaults to:open_street_maps
.:api_key
: (Optional) The API key required by some providers.- Other options specific to the chosen provider may also be passed.
Returns
{:ok, %Result{}}
: On success, returns a tuple with:ok
and aGeolixir.Result
struct containing coordinates, location details, bounds, and metadata.{:error, reason}
: On failure, returns a tuple with:error
and the reason (e.g.,:no_results_found
,:invalid_api_key
, HTTP error details).
Examples
iex> Geolixir.geocode("Eiffel Tower, Paris")
{:ok, %Geolixir.Result{coordinates: %Geolixir.Coords{lat: 48.858..., lon: 2.294...}, ...}}
iex> Geolixir.geocode("NonExistentPlace12345", provider: :open_street_maps)
{:error, :no_results_found} # Example error, actual error may vary
iex> Geolixir.geocode("Statue of Liberty", provider: :geoapify, api_key: "YOUR_KEY")
{:ok, %Geolixir.Result{...}} # Requires a valid Geoapify key
iex> Geolixir.geocode("Some Address", provider: :unknown_provider)
** (ArgumentError) Unknown provider: unknown_provider. Available providers: [...]
@spec reverse_geocode(lat :: float(), lon :: float(), opts :: keyword()) :: {:ok, Geolixir.Result.t()} | {:error, atom() | map()}
Reverse geocodes geographical coordinates (latitude and longitude) into an address.
It uses the configured default provider unless a specific :provider
is
specified in the options. Some providers may require an :api_key
.
Parameters
lat
: The latitude.lon
: The longitude.opts
: A keyword list of options.:provider
: (Optional) The atom representing the provider module to use (e.g.,:geoapify
,:open_street_maps
). Defaults to:open_street_maps
.:api_key
: (Optional) The API key required by some providers.- Other options specific to the chosen provider may also be passed.
Returns
{:ok, %Result{}}
: On success, returns a tuple with:ok
and aGeolixir.Result
struct containing location details, coordinates, bounds, and metadata.{:error, reason}
: On failure, returns a tuple with:error
and the reason (e.g.,:no_results_found
,:invalid_coordinates
, HTTP error details).
Examples
iex> Geolixir.reverse_geocode(40.7128, -74.0060) # New York City Hall approx.
{:ok, %Geolixir.Result{location: %Geolixir.Location{formatted_address: "City Hall Park, ...", ...}, ...}}
iex> Geolixir.reverse_geocode(999.0, 999.0)
{:error, :invalid_coordinates} # Example error, actual error may vary
iex> Geolixir.reverse_geocode(51.5074, -0.1278, provider: :position_stack, api_key: "YOUR_KEY")
{:ok, %Geolixir.Result{...}} # Requires a valid PositionStack key