Geolixir.Provider behaviour (geolixir v0.1.3)

View Source

Defines the behavior for all Geolixir geocoding providers.

Each provider module must implement the required callbacks defined here. This ensures a consistent interface across different geocoding services.

Providers typically handle:

  • Constructing the correct API request URL and parameters.
  • Making the HTTP request via Geolixir.HttpClient.
  • Parsing the response from the specific provider's format.
  • Transforming the parsed data into the standardized Geolixir.Result struct.
  • Handling provider-specific errors and API key requirements.

Summary

Callbacks

Callback for geocoding a single address.

Callback for geocoding a list of addresses (batch operation). Optional.

Callback for reverse geocoding a single pair of coordinates.

Callback for reverse geocoding a list of coordinates (batch operation). Optional.

Callbacks

geocode(payload, opts)

@callback geocode(payload :: map(), opts :: keyword()) ::
  {:ok, Geolixir.Result.t()} | {:error, any()}

Callback for geocoding a single address.

Parameters

  • payload: A map containing the data needed for geocoding (e.g., %{address: "..."}).
  • opts: A keyword list of options, potentially including :api_key and provider-specific settings.

Return Values

  • {:ok, Result.t()}: On success.
  • {:error, reason}: On failure.

geocode_list(payload, opts)

(optional)
@callback geocode_list(payload :: map(), opts :: keyword()) ::
  {:ok, [Geolixir.Result.t()]} | {:error, any()}

Callback for geocoding a list of addresses (batch operation). Optional.

Parameters

  • payload: A map containing the data needed for batch geocoding (e.g., %{addresses: [...]}).
  • opts: A keyword list of options.

Return Values

  • {:ok, list(Result.t())}: On success.
  • {:error, reason}: On failure.

reverse_geocode(payload, opts)

@callback reverse_geocode(payload :: map(), opts :: keyword()) ::
  {:ok, Geolixir.Result.t()} | {:error, any()}

Callback for reverse geocoding a single pair of coordinates.

Parameters

  • payload: A map containing the data needed for reverse geocoding (e.g., %{lat: ..., lon: ...}).
  • opts: A keyword list of options.

Return Values

  • {:ok, Result.t()}: On success.
  • {:error, reason}: On failure.

reverse_geocode_list(payload, opts)

(optional)
@callback reverse_geocode_list(payload :: map(), opts :: keyword()) ::
  {:ok, [Geolixir.Result.t()]} | {:error, any()}

Callback for reverse geocoding a list of coordinates (batch operation). Optional.

Parameters

  • payload: A map containing the data needed for batch reverse geocoding (e.g., %{coordinates: [%{lat: ..., lon: ...}, ...]}).
  • opts: A keyword list of options.

Return Values

  • {:ok, list(Result.t())}: On success.
  • {:error, reason}: On failure.