IPStack for Node.JS (Geo Location Library)

IPStack for Node.JS is a simple library used to interface with an IPStack Geo API.

$ npm i ipstackgeo-js

Learn more about IPStack here: ipstack.net

Looking for the Python version?

Looking for the PHP version?

Features

• Retrieve the Geo Location data for any IP address.
• Retrieve the Geo Location data for the system executing this code.
• Retrieve the Geo Location data for a client.
• Retrieve the Geo Location data for a batch of IP addresses.
• Assess the security of an IP address.

Basic Usage

const geoLookup = require(`ipstackgeo-js`)('<YOUR-API-KEY>');

geoLookup.forSelf().then(
    res => console.log(res),
    err => console.log(err)
);

Example Usage

Note: See IPStack: Response Objects for a list of available properties in a response object.

Create the GeoLookup Object

const geoLookup = require(`ipstackgeo-js`)('<YOUR-API-KEY>');

Lookup a location for an IP Address

// Retrieve the location information for 
// github.com by using it's hostname.
// 
// This function will work with hostnames
// or IP addresses.
geoLookup.forIps('github.com')
    .then(
        (res) => console.log(res),
        (err) => console.log(err)
    );

Look up own location

geoLookup.forSelf().then(
    (res) => console.log(res),
    (err) => console.log(err)
);

Other Features

There are also a few other useful features built into this library and the IPStack API.

1. Bulk Location Lookup

   The ipstack API also offers the ability to request data for multiple IPv4 or IPv6 addresses at the same time. This requires the PROFESSIONAL teir API key or higher and is limitted to 50 IPs at a time.

   See: https://ipstack.com/documentation#bulk

   const ips = ['google.com', 'github.com', '1.1.1.1'];
   geoLookup.forIps(...ips).then(
       (res) => console.log(res),
       (err) => console.log(err)
   );

2. Requesting the hostname for an IP address.

   By default, the ipstack API does not return information about the hostname the given IP address resolves to. In order to include the hostname use the following.

   See: https://ipstack.com/documentation#hostname

   geoLookup.forIps('1.1.1.1')
       .lookupHostname()
       .then(
           (res) => console.log(res.hostname),
           (err) => console.log(err)
       );

   Output:

   one.one.one.one

3. Assessing Security

   Customers subscribed to the Professional Plus Plan may access the ipstack API's Security Module, which can be used to assess risks and threats originating from certain IP addresses before any harm can be done to a website or web application.

   See: https://ipstack.com/documentation#security

   geoLookup.forIps('1.1.1.1')
       .assessSecurity()
       .then(
           (res) => console.log(res),
           (err) => console.log(err)
       );

4. Set the language for a response

   The ipstack API is capable of delivering its result set in different languages. To request data in a language other than English (default) use following with one of the supported language codes.

   See: https://ipstack.com/documentation#language

   Supported Langauges

   geoLookup.forSelf()
       .language('en')
       .then(
           (res) => console.log(res),
           (err) => console.log(err)
       );

5. Configuring your request

   geoLookup.forSelf()
       /// Use HTTPS. Note: This requires IPStack Basic plan or higher.
       .useHttps()
       /// Configure the timeout for requests
       .timeout(15000)
       .then(
           (res) => console.log(res),
           (err) => console.log(err)
       );

6. Using JSONP Callbacks

   The ipstack API supports JSONP Callbacks, enabling you to enter a function name and cause the API to return your requested API result wrapped inside that function.

   See: https://ipstack.com/documentation#jsonp

   geoLookup.forIp()
       .jsonp('someSpecialFunctionName')
       .then(
           // When using jsonp(), res will be a string instead of an object.
           (res) => console.log(res),
           (err) => console.log(err)
       );

   Output:

   someSpecialFunctionName({ ... });