ipdata

Official Erlang client library for the ipdata.co IP geolocation and threat intelligence API.

Features

• IP geolocation (city, region, country, continent, coordinates)
• ASN and company data
• Carrier detection (mobile network operator)
• Timezone, currency, and language detection
• Threat intelligence (Tor, VPN, proxy, datacenter, blocklists)
• Bulk lookups (up to 100 IPs per request)
• Field filtering to reduce response size
• EU endpoint support for data residency
• Production-ready with proper TLS verification and error handling

Requirements

• Erlang/OTP 25 or later
• rebar3

Installation

Add ipdata to your rebar.config dependencies:

{deps, [
    {ipdata, "~> 1.0"}
]}.

Quick Start

%% Start the application
application:ensure_all_started(ipdata).

%% Create a client with your API key
{ok, Client} = ipdata:new(<<"YOUR_API_KEY">>).

%% Look up an IP address
{ok, Result} = ipdata:lookup(Client, <<"8.8.8.8">>).
maps:get(<<"country_name">>, Result).
%% => <<"United States">>

Usage

Create a Client

%% Default options (global endpoint, 5s timeout)
{ok, Client} = ipdata:new(<<"YOUR_API_KEY">>).

%% Use the EU endpoint for data residency
{ok, Client} = ipdata:new(<<"YOUR_API_KEY">>, #{endpoint => eu}).

%% Custom endpoint and timeout
{ok, Client} = ipdata:new(<<"YOUR_API_KEY">>, #{
    endpoint => <<"https://custom-api.example.com">>,
    timeout => 10000
}).

Look Up Your Own IP

{ok, Result} = ipdata:lookup(Client).

Look Up a Specific IP

{ok, Result} = ipdata:lookup(Client, <<"8.8.8.8">>).

%% Access response fields
maps:get(<<"ip">>, Result).           %% => <<"8.8.8.8">>
maps:get(<<"country_name">>, Result). %% => <<"United States">>
maps:get(<<"city">>, Result).         %% => <<"Ashburn">>
maps:get(<<"latitude">>, Result).     %% => 39.03
maps:get(<<"longitude">>, Result).    %% => -77.5

%% Nested data
ASN = maps:get(<<"asn">>, Result).
maps:get(<<"name">>, ASN).            %% => <<"Google LLC">>

Threat = maps:get(<<"threat">>, Result).
maps:get(<<"is_vpn">>, Threat).       %% => false

TimeZone = maps:get(<<"time_zone">>, Result).
maps:get(<<"name">>, TimeZone).       %% => <<"America/New_York">>

Filter Response Fields

Request only the fields you need to reduce response size and improve performance:

{ok, Result} = ipdata:lookup(Client, <<"8.8.8.8">>,
                              [<<"ip">>, <<"country_name">>, <<"city">>]).
%% Result contains only the requested fields

Bulk Lookup

Look up multiple IP addresses in a single request (up to 100, requires a paid plan):

{ok, Results} = ipdata:bulk(Client, [<<"8.8.8.8">>, <<"1.1.1.1">>]).
%% Results is a list of maps, one per IP

%% With field filtering
{ok, Results} = ipdata:bulk(Client, [<<"8.8.8.8">>, <<"1.1.1.1">>],
                             [<<"ip">>, <<"country_name">>]).

Error Handling

All functions return {ok, Result} on success or {error, Reason} on failure:

case ipdata:lookup(Client, <<"8.8.8.8">>) of
    {ok, Result} ->
        io:format("Country: ~s~n", [maps:get(<<"country_name">>, Result)]);
    {error, {http_error, 401, Message}} ->
        io:format("Authentication failed: ~s~n", [Message]);
    {error, {http_error, 403, Message}} ->
        io:format("Forbidden: ~s~n", [Message]);
    {error, {http_error, 429, Message}} ->
        io:format("Rate limited: ~s~n", [Message]);
    {error, {request_failed, Reason}} ->
        io:format("Network error: ~p~n", [Reason]);
    {error, {json_error, Reason}} ->
        io:format("JSON parse error: ~p~n", [Reason])
end.

API Reference

ipdata:new/1,2

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

Create a new client. Options:

ipdata:lookup/1,2,3

-spec lookup(Client) -> {ok, map()} | {error, term()}.
-spec lookup(Client, IP :: binary()) -> {ok, map()} | {error, term()}.
-spec lookup(Client, IP :: binary(), Fields :: [binary()]) -> {ok, map()} | {error, term()}.

Look up geolocation and metadata for an IP address.

ipdata:bulk/2,3

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

Look up multiple IP addresses in a single request. Maximum 100 IPs. Requires a paid API key.

Response Fields

Threat Fields

Testing

rebar3 ct

License

MIT - see LICENSE for details.