npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

@ipregistry/client

v6.0.0

Published

Official Ipregistry Javascript Library.

Downloads

10,590

Readme

Ipregistry Javascript Client Library

License Actions Status npm tsdoc

This is the official Javascript client library for the Ipregistry IP geolocation and threat data API, allowing you to lookup your own IP address or specified ones. Responses return multiple data points including carrier, company, currency, location, 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 install @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('YOUR_API_KEY');

client.lookupIp('73.2.2.2').then(response => {
    console.log(response.data);
}).catch(error => {
    console.error(error);
})

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

const {IpregistryClient} = require('@ipregistry/client');

const client = new IpregistryClient('YOUR_API_KEY');

async function lookupIpInfo(ip) {
    try {
        const response = await client.lookupIp('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.error(error);
    }
}

lookupIpInfo();

Or with TypeScript:

import {ApiError, ApiResponse, ClientError, IpInfo, IpregistryClient} from '@ipregistry/client';

async function main() {
    const client: IpregistryClient = new IpregistryClient('tryout')

    try {
        const response: ApiResponse<IpInfo> =
            await client.lookupIp('73.2.2.7')

        // 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) {
            // Handle API error here (e.g. Invalid API key or IP address)
            console.error('API error', error)
        } else if (error instanceof ClientError) {
            // Handle client error here (e.g. request timeout)
            console.error('Client error', error)
        } else {
            // Handle unexpected error here
            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('YOUR_API_KEY');
    
    client.lookupIp('73.2.2.2').then(response => {
        console.log(response.data);
    }).catch(error => {
        console.error(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 disabled. Below are examples to enable and configure a caching strategy. Once enabled, the default cache implementation memoizes for 10min the most 2048 recently used lookups on server side (16 when used in a browser).

Make sure you do not create an Ipregistry client per request, otherwise caching will have no effect. In the case you are using a Function-as-a-Service (e.g. AWS Lambda, Firebase Function, Google Cloud Function), then you should declare an Ipregistry client variable in global scope. This way, the Ipregistry client states can be reused in subsequent invocations.

Enabling caching

Caching up to 16384 entries:

const client = new IpregistryClient('YOUR_API_KEY', new InMemoryCache(16384));

Configuring cache max age

Caching up to 16384 entries for at most 6 hours:

const client = new IpregistryClient('YOUR_API_KEY', new InMemoryCache(16384, 3600 * 6 * 1000));

If your purpose is to re-use a same Ipregistry client instance (and thus share the same cache) for different API keys, then you can alter the current configuration to set the API key to use before each request:

client.config.apiKey = 'YOUR_NEW_API_KEY';

Disabling caching

const client = new IpregistryClient('YOUR_API_KEY', 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.lookupIp('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-Agents header. To ease this process, the library includes a utility function:

UserAgents.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.lookupIp('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.lookupIp('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);

European Union base URL

For clients operating within the European Union or for those who prefer to route their requests through our EU servers, the Ipregistry client library provides an easy way to configure this preference using the withEuBaseURL option. This ensures that your requests are handled by our EU-based infrastructure, potentially reducing latency and aligning with local data handling regulations:

const config = new IpregistryConfigBuilder('tryout').withEuBaseUrl().build()
const client = new IpregistryClient(config)

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.