Need private packages and team management tools?Check out npm Teams »

@ipregistry/client

2.0.0 • Public • Published

Ipregistry

Ipregistry Javascript Client Library

License Travis npm

This is the official Java client library for the Ipregistry IP geolocation and threat data API, allowing you to lookup your own IP address or specified ones. Responses return up to 65 data points including location, currency, timezone, threat information, and more.

Getting Started

You'll need an Ipregistry API key, which you can get along with 100,000 free lookups by signing up for a free account at https://ipregistry.co.

Installation

Npm

$ npm install @ipregistry/client

Yarn

$ yarn add @ipregistry/client

First example

This is a very simple example. This creates a Ipregistry client and retrieves IP info for a given IP address:

const {IpregistryClient} = require('@ipregistry/client');
 
const client = new IpregistryClient('tryout');
 
client.lookup('73.2.2.2').then(response => {
    console.log(response.data);
}).catch(error => {
    console.err(error);
})
 

Instead of using promises, you can also use async/await:

const {IpregistryClient} = require('@ipregistry/client');
 
const client = new IpregistryClient('tryout');
 
async function lookupIpInfo(ip) {
    try {
        const response = await client.lookup('73.2.2.2');
        // Get location, threat data and more
        console.log(response.data.location.country.code);
        console.log(response.data.currency.code);
        console.log(response.data.security.is_threat);
    } catch(error) {
        console.err(error);
    }
}
 
lookupIpInfo();

Or with TypeScript:

import {ApiError, ClientError, IpregistryClient} from '@ipregistry/client';
 
async function main() {
    const client = new IpregistryClient('tryout');
 
    try {
        const response = await client.lookup('73.2.2.2');
        // Get location, threat data and more
        console.log(response.data.location.country.code);
        console.log(response.data.currency.code);
        console.log(response.data.security.is_threat);
    } catch (error) {
        if (error instanceof ApiError) {
            console.error('API error', error);
        } else if (error instanceof ClientError) {
            console.error('Client error', error);
        } else {
            console.error('Unexpected error', error);
        }
    }
}
 
main().then(() => 0).catch(() => 1);

Browser support:

<script src="https://unpkg.com/@ipregistry/client/dist/browser/index.js"></script>
<script>
    const client = new ipregistry.IpregistryClient('tryout');
    
    client.lookup('73.2.2.2').then(response => {
        console.log(response.data);
    }).catch(error => {
        console.err(error);
    });
</script>

More samples are available in the samples folder.

Caching

The Ipregistry client library has built-in support for in-memory caching. By default caching is enabled and the default policy memoizes for 10min the most 2048 recently used lookups on server side (16 when used in a browser).

Configuring cache size

Caching up to 16384 entries:

const client = new IpregistryClient('tryout', new DefaultCache(16384));

Configuring cache max age

Caching up to 16384 entries for at most 6 hours:

const client = new IpregistryClient('tryout', new DefaultCache(16384, 3600 * 6 * 1000));

Disabling caching

const client = new IpregistryClient('tryout', new NoCache());

Enabling hostname lookup

By default, the Ipregistry API does not return information about the hostname a given IP address resolves to. In order to include the hostname value in your API result, you need to enable the feature explicitly:

const ipInfo = await client.lookup('73.2.2.2', IpregistryOptions.hostname(true));

Errors

All Ipregistry errors inherit IpregistryError class.

Main subtypes are ApiError and ClientError.

Errors of type ApiError include a code field that maps to the one described in the Ipregistry documentation.

Filtering bots

You might want to prevent Ipregistry API requests for crawlers or bots browsing your pages.

A manner to proceed is to identify bots using User-Agent header. To ease this process, the library includes a utility function:

UserAgent.isBot('TO_REPLACE_BY_USER_AGENT_RETRIEVED_FROM_REQUEST_HEADER')

Please note that when caching is disabled, some of the fields above may be null when the content is retrieved from the cache and no request is made to the Ipregistry API.

Selecting fields

To save bandwidth and speed up response times, the API allows selecting fields to return:

const response = await client.lookup('73.2.2.2', IpregistryOptions.filter('hostname,location.country.name'));

Usage data

Looking to know the number of credits a request consumed? how much is remaining? or simply get throttling info about an API key for which you have enabled rate limiting?

All client responses are of type ApiResponse and include data about credits and throttling.

const response = await client.lookup('73.2.2.2');
console.log(response.credits.consumed);
console.log(response.credits.remaining);
console.log(response.throttling.limit);
console.log(response.throttling.remaining);
console.log(response.throttling.reset);

Other Libraries

There are official Ipregistry client libraries available for many languages including Java, Python, and more.

Are you looking for an official client with a programming language or framework we do not support yet? let us know.

Install

npm i @ipregistry/client

DownloadsWeekly Downloads

166

Version

2.0.0

License

Apache-2.0

Unpacked Size

239 kB

Total Files

65

Last publish

Collaborators

  • avatar