ipdata (ipdata v1.1.0)

View Source

Erlang client library for the ipdata.co API.

Provides IP geolocation, threat intelligence, ASN, carrier, timezone, currency, and other IP metadata lookups.

Quick Start

   application:ensure_all_started(ipdata).
   {ok, Client} = ipdata:new(<<"YOUR_API_KEY">>).
   {ok, Result} = ipdata:lookup(Client, <<"8.8.8.8">>).
   maps:get(<<"country_name">>, Result).

Endpoints

By default the global endpoint is used. You can specify the EU endpoint or a custom URL via options:

   {ok, Client} = ipdata:new(<<"KEY">>, #{endpoint => eu}).
   {ok, Client} = ipdata:new(<<"KEY">>, #{endpoint => <<"https://custom.example.com">>}).

Summary

Functions

Look up multiple IP addresses in a single request.

Look up multiple IP addresses, returning only the specified fields.

Look up the IP address of the calling machine.

Look up a specific IP address.

Look up a specific IP address, returning only the specified fields.

Create a new ipdata client with default options.

Create a new ipdata client with custom options.

Types

bulk_error/0

-type bulk_error() :: lookup_error() | {invalid_input, binary()}.

client/0

-type client() :: #{api_key := binary(), endpoint := binary(), timeout := pos_integer()}.

lookup_error/0

-type lookup_error() ::
          {json_error, term()} | {request_failed, term()} | {http_error, non_neg_integer(), binary()}.

opts/0

-type opts() :: #{endpoint => global | eu | binary(), timeout => pos_integer()}.

Functions

bulk(Client, IPs)

-spec bulk(Client :: client(), IPs :: [binary()]) -> {ok, [map()]} | {error, bulk_error()}.

Look up multiple IP addresses in a single request.

Accepts up to 100 IP addresses. Requires a paid API key.

bulk(Client, IPs, Fields)

-spec bulk(Client :: client(), IPs :: [binary()], Fields :: [binary()]) ->
              {ok, [map()]} | {error, bulk_error()}.

Look up multiple IP addresses, returning only the specified fields.

Accepts up to 100 IP addresses. Requires a paid API key.

Example:

  ipdata:bulk(Client, [<<"8.8.8.8">>, <<"1.1.1.1">>],
              [<<"country_name">>, <<"ip">>]).

lookup(Client)

-spec lookup(Client :: client()) -> {ok, #{atom() | binary() => term()}} | {error, lookup_error()}.

Look up the IP address of the calling machine.

lookup(Client, IP)

-spec lookup(Client :: client(), IP :: binary()) ->
                {ok, #{atom() | binary() => term()}} | {error, lookup_error()}.

Look up a specific IP address.

The IP can be an IPv4 or IPv6 address as a binary string.

lookup(Client, IP, Fields)

-spec lookup(Client :: client(), IP :: binary(), Fields :: [binary()]) ->
                {ok, #{atom() | binary() => term()}} | {error, lookup_error()}.

Look up a specific IP address, returning only the specified fields.

Fields is a list of field name binaries to include in the response. Pass an empty IP binary (<<>>) to look up the caller's own IP.

Example:

  ipdata:lookup(Client, <<"8.8.8.8">>, [<<"country_name">>, <<"city">>]).

new(ApiKey)

-spec new(ApiKey :: binary()) -> {ok, client()} | {error, term()}.

Create a new ipdata client with default options.

Uses the global endpoint and a 5 second timeout.

new(ApiKey, Opts)

-spec new(ApiKey :: term(), Opts :: term()) -> {ok, client()} | {error, term()}.

Create a new ipdata client with custom options.

Options:

  • endpoint - global (default), eu, or a custom URL binary
  • timeout - Request timeout in milliseconds (default 5000)