ipregistry (ipregistry v1.0.0)
View SourceOfficial Erlang client for the Ipregistry (https://ipregistry.co) IP geolocation and threat data API.
Create a client with new/1 or new/2, then perform lookups:
Client = ipregistry:new(<<"YOUR_API_KEY">>),
{ok, Info} = ipregistry:lookup(Client, <<"8.8.8.8">>),
CountryName = ipregistry:get(Info, [location, country, name]).Responses are returned as maps with binary keys, exactly as decoded from the API's JSON. Use get/2 and get/3 to reach nested fields conveniently.
A client is a plain immutable map, so it is safe to share between processes, embed in a supervisor's child state, or store in application configuration.
Summary
Types
An error reported by the Ipregistry API. code is one of the codes listed at https://ipregistry.co/docs/errors (for example <<"INVALID_API_KEY">>). status is the HTTP status, present when the whole request failed.
One entry of a batch lookup; each entry succeeds or fails independently.
Options accepted by new/2. See the README for the full reference.
api_error means the API rejected the request; client_error covers failures that happen on the client side (invalid input, transport errors, undecodable responses).
An IPv4 or IPv6 address, as a binary, a string, or an inet address tuple.
Decoded API response: a map with binary keys mirroring the JSON payload.
Per-request options: fields selects response fields using Ipregistry's field selector syntax, hostname enables reverse-DNS resolution, and params sets arbitrary extra query parameters.
Functions
Equivalent to batch_lookup(Client, Ips, #{}).
Looks up several IP addresses at once.
Returns the default API base URL, https://api.ipregistry.co.
Returns the European Union API base URL, https://eu.api.ipregistry.co. Pass it as the base_url option to new/2 to have your data processed in the EU only.
Equivalent to get(Info, Path, undefined).
Returns the value at the given path inside a response map, or Default when any path element is absent.
Equivalent to lookup(Client, Ip, #{}).
Looks up the data associated with the given IP address.
Equivalent to new(ApiKey, #{}).
Creates a client authenticating with the given API key.
Equivalent to origin_lookup(Client, #{}).
Looks up the IP address the request originates from.
Parses one or more raw User-Agent strings (such as the User-Agent header of an incoming HTTP request) into structured data.
Types
-type api_error() :: #{code := binary(), message := binary(), resolution := binary(), status => non_neg_integer()}.
An error reported by the Ipregistry API. code is one of the codes listed at https://ipregistry.co/docs/errors (for example <<"INVALID_API_KEY">>). status is the HTTP status, present when the whole request failed.
One entry of a batch lookup; each entry succeeds or fails independently.
-type client() :: #{api_key := binary(), base_url := binary(), timeout := pos_integer(), max_retries := non_neg_integer(), retry_interval := pos_integer(), retry_on_server_error := boolean(), retry_on_too_many_requests := boolean(), max_batch_size := pos_integer(), batch_concurrency := pos_integer(), cache := atom() | pid() | undefined, user_agent := binary()}.
An immutable client configuration created by new/2.
-type client_options() :: #{base_url => binary() | string(), timeout => pos_integer(), max_retries => non_neg_integer(), retry_interval => pos_integer(), retry_on_server_error => boolean(), retry_on_too_many_requests => boolean(), max_batch_size => pos_integer(), batch_concurrency => pos_integer(), cache => atom() | pid() | undefined, user_agent => binary() | string()}.
Options accepted by new/2. See the README for the full reference.
api_error means the API rejected the request; client_error covers failures that happen on the client side (invalid input, transport errors, undecodable responses).
-type ip() :: binary() | string() | inet:ip_address().
An IPv4 or IPv6 address, as a binary, a string, or an inet address tuple.
Decoded API response: a map with binary keys mirroring the JSON payload.
-type lookup_options() :: #{fields => binary() | string(), hostname => boolean(), params => #{atom() | binary() | string() => binary() | string()}}.
Per-request options: fields selects response fields using Ipregistry's field selector syntax, hostname enables reverse-DNS resolution, and params sets arbitrary extra query parameters.
Functions
-spec batch_lookup(client(), [ip()]) -> {ok, [batch_result()]} | {error, error_reason()}.
Equivalent to batch_lookup(Client, Ips, #{}).
Looks up several IP addresses at once.
-spec batch_lookup(client(), [ip()], lookup_options()) -> {ok, [batch_result()]} | {error, error_reason()}.
Looks up several IP addresses at once.
Returns results in the same order as the input. Each entry may independently succeed or fail (for example on an invalid address), so inspect entries element by element:
{ok, Results} = ipregistry:batch_lookup(Client, [<<"8.8.8.8">>, <<"1.1.1.1">>]),
lists:foreach(
fun({ok, Info}) -> io:format("~ts~n", [ipregistry:get(Info, [location, country, name])]);
({error, {api_error, #{code := Code}}}) -> io:format("failed: ~ts~n", [Code])
end, Results).The API accepts up to 1024 addresses per request; larger lists are transparently split into several requests dispatched with bounded concurrency (see the max_batch_size and batch_concurrency client options) and results are reassembled in input order. An overall {error, ...} return means the whole request failed (for example on authentication or network errors), not that an individual entry did.
Entries already present in the cache are served locally; only the remainder are requested from the API.
-spec default_base_url() -> binary().
Returns the default API base URL, https://api.ipregistry.co.
-spec eu_base_url() -> binary().
Returns the European Union API base URL, https://eu.api.ipregistry.co. Pass it as the base_url option to new/2 to have your data processed in the EU only.
Equivalent to get(Info, Path, undefined).
Returns the value at the given path inside a response map, or undefined when any path element is absent.
Returns the value at the given path inside a response map, or Default when any path element is absent.
Path elements may be atoms, binaries, or strings; they are matched against the response's binary keys:
ipregistry:get(Info, [location, country, name]).
ipregistry:get(Info, [security, is_vpn], false).-spec lookup(client(), ip()) -> {ok, ip_info()} | {error, error_reason()}.
Equivalent to lookup(Client, Ip, #{}).
Looks up the data associated with the given IP address.
-spec lookup(client(), ip(), lookup_options()) -> {ok, ip_info()} | {error, error_reason()}.
Looks up the data associated with the given IP address.
The address may be a binary, a string, or an inet:ip_address() tuple. To look up the requester's own IP address use origin_lookup/1 instead. When the client is configured with a cache, a cache hit is returned without contacting the API.
Equivalent to new(ApiKey, #{}).
Creates a client with default settings.
-spec new(binary() | string(), client_options()) -> client().
Creates a client authenticating with the given API key.
You can obtain a key, along with a generous free tier, at https://ipregistry.co. Ipregistry's OTP applications (inets, ssl) are started if they are not running already.
Raises error({invalid_option, ...}) or error(empty_api_key) on invalid configuration, since a misconfigured client is a programming error rather than a runtime condition to handle.
-spec origin_lookup(client()) -> {ok, ip_info()} | {error, error_reason()}.
Equivalent to origin_lookup(Client, #{}).
Looks up the IP address the request originates from.
-spec origin_lookup(client(), lookup_options()) -> {ok, ip_info()} | {error, error_reason()}.
Looks up the IP address the request originates from.
The response additionally carries parsed User-Agent data under the <<"user_agent">> key. Origin lookups are never cached, because the requester IP is only known from the response.
-spec parse_user_agents(client(), [binary() | string()]) -> {ok, [batch_result()]} | {error, error_reason()}.
Parses one or more raw User-Agent strings (such as the User-Agent header of an incoming HTTP request) into structured data.
Results preserve the order of the input, and each entry may independently succeed or fail, like batch_lookup/3 results.