IPGeolocation-Logo

IP Geolocation API JavaScript SDK

Overview

The official JavaScript Library for IPGeolocation.io's set of APIs, provides a quick, developer friendly way to access IP Location, Security, Timezone, Astronomy, ASN, Abuse Contact, and useragent data. Lookup your own IP or provide any IPv4, IPv6 or domain name to get structured results in JavaScript (JS), without the need for manual HTTP requests handling.

  • IP Location API: Get all-in-one unified solution for location (city, locality, state, country, etc.), currency, network (AS number, ASN name, organization, asn type, date of allocation, company/ISP name, company type, company domain), timezone , useragent string parsing, security (threat score, is_tor, is_bot, proxy_provider, cloud_provider), and abuse contact (route/CIDR network, country, address, email, phone numbers) information.
  • IP Security API: Get security, network, location, hostname, timezone and useragent parsing.
  • ASN API: Get ASN details along with peers, upstreams, downstreams, routes, and raw WHOIS.
  • Abuse Contact API: Get abuse emails, phone numbers, kind, organization, route/CIDR network and country.
  • Astronomy API: Get sunrise, sunset, moonrise, moonset, moon phases with precise twilight period times in combination with location information.
  • Timezone API: Get timezone name, multiple time formats, daylight saving status and its details along with location information.
  • Timezone Convert API: Convert time between timezone names, geo coordinates, location addresses, IATA codes, ICAO codes, or UN/LOCODE.
  • User Agent API: Get browser, Operating System, and device info from single or multiple Useragent string parsing.

This library aims to empower developers to integrate threat intelligence, personalization, fraud prevention, compliance, and analytics features directly into web based applications. Whether you're enriching signup forms with ip geolocation data, localizing content, embedding threat intelligence in back-end systems, or converting time zones and currencies, the library ensures seamless, scalable integration with IPGeolocation.io’s global API infrastructure.

Based on:

  • API version: 2.0

Official Release:

Requirements

Installation

1.Using NPM

Install the SDK directly from NPM :

npm install ip-geolocation-api-javascript-sdk

2.Using Yarn

Alternatively, if you use Yarn:

yarn add ip-geolocation-api-javascript-sdk

3.Manual Installation

To include the SDK manually:

1.
Clone this repository:
git clone https://github.com/ipgeolocation/ip-geolocation-api-javascript-sdk.git
2.
Navigate to the project folder and install dependencies:
npm install

or with Yarn:

yarn install

API Plan Tiers and Documentation

The documentation below corresponds to the four available API tier plans:

For a detailed comparison of what each plan offers, visit the Pricing Page.

API Endpoints

All URIs are relative to https://api.ipgeolocation.io/v2

ClassMethodHTTP requestDescription
IPGeolocationAPIgetIpGeolocationGET /ipgeoGet geolocation data for a single IP address
IPGeolocationAPIgetBulkIpGeolocationPOST /ipgeo-bulkGet geolocation data for multiple IP addresses
IPSecurityAPIgetIpSecurityInfoGET /securityGet threat intelligence for a single IP address
IPSecurityAPIgetBulkIpSecurityInfoPOST /security-bulkGet threat intelligence for multiple IP addresses
ASNLookupAPIgetAsnInfoGET /asnGet details of any ASN number
AbuseContactAPIgetAbuseContactInfoGET /abuseRetrieve abuse contact data for an IP address
AstronomyAPIgetAstronomyDetailsGET /astronomyGet sun and moon timings and positions
TimezoneAPIgetTimezoneInfoGET /timezoneGet timezone information based on IP, coordinates, or name
TimeConversionAPIconvertTimeBetweenTimezonesGET /timezone/convertConvert time from one timezone to another
UserAgentAPIgetUserAgentDetailsGET /user-agentParse a single user-agent string
UserAgentAPIparseBulkUserAgentStringsPOST /user-agent-bulkParse multiple user-agent strings
UserAgentAPIparseUserAgentStringPOST /user-agentAlternate method to parse a single user-agent string

Fields and Methods Availability

IP Geolocation offers four plans from billing point of view: Free, Standard, Security, Advance. The availability of each method calling from the respective class, over all plans are presented below.

ClassMethodFreeStandardSecurityAdvance
IPGeolocationAPIgetIpGeolocationTickTickCrossTick
IPGeolocationAPIgetBulkIpGeolocationCrossTickCrossTick
IPSecurityAPIgetIpSecurityInfoCrossCrossTickCross
IPSecurityAPIgetBulkIpSecurityInfoCrossCrossTickCross
ASNLookupAPIgetAsnInfoCrossCrossCrossTick
AbuseContactAPIgetAbuseContactInfoCrossCrossCrossTick
AstronomyAPIgetAstronomyDetailsTickTickTickTick
TimezoneAPIgetTimezoneInfoTickTickTickTick
TimeConversionAPIconvertTimeBetweenTimezonesTickTickTickTick
UserAgentAPIgetUserAgentDetailsTickTickTickTick
UserAgentAPIparseBulkUserAgentStringsTickTickTickTick
UserAgentAPIparseUserAgentStringCrossTickTickTick
Tip

The availability of fields in every API endpoint across all API plans is provided in the Reference Table within each respective API Documentation. e.g., for IPGeolocationApi, please visit https://ipgeolocation.io/ip-location-api.html#reference-to-ipgeolocation-api-response.

Authentication Setup

To authenticate API requests, you'll need an API key from ipgeolocation.io.

1.How to Get Your API Key

  1. Sign up here: https://app.ipgeolocation.io/signup
  2. (optional) Verify your email, if you signed up using email.
  3. Log in to your account: https://app.ipgeolocation.io/login
  4. After logging in, navigate to your Dashboard to find your API key: https://app.ipgeolocation.io/dashboard

2.ApiKeyAuth

Once you have the key, initialize the SDK client with it:

const { APIClient } = require('ip-geolocation-api-javascript-sdk');

const client = APIClient.instance;
client.authentications['ApiKeyAuth'].apiKey = 'YOUR_API_KEY_HERE';

3.Request Origin - keyless access

If you don't set an API key, the IPGeolocation API can still authenticate your request using request origin. This is useful if:

  • You're using the SDK from a browser or server with allowed referrer/IP
  • Your keyless usage is enabled in the dashboard, by adding your domain name as Request Origin in Add API key section.

See this section for more details.

In this case, just skip setting the API key, and the API will automatically detect your request origin:

const { APIClient } = require('ip-geolocation-api-javascript-sdk');
const client = APIClient.instance;
// No API key set — will use request origin

IP Geolocation Examples

This section shows how to use the getIpGeolocation() method from the JavaScript SDK across Free, Standard, and Advanced subscription tiers. Each example highlights different parameter combinations: fields , include , and excludes .

Parameters

  • fields : Use this parameter to include specific fields in the response.
  • excludes : Use this parameter to omit specific fields from the response.
  • include : Use this parameter to add optional modules to the response, such as:
    • security
    • user_agent
    • hostname
    • liveHostname
    • hostnameFallbackLive
    • abuse
    • dma
    • timezone

For the full list of supported fields/modules, refer to the IP Geolocation API Docs.

The ip parameter in the SDK can accept any valid IPv4 address, IPv6 address, or domain name. If the ip= parameter is not specified, the API will return information about the public IP of the machine.

1.Developer (Free) Plan Examples

I.Get Default Fields

const { IPGeolocationAPI }  = require('ip-geolocation-api-javascript-sdk');

const api = new IPGeolocationAPI();

api.getIpGeolocation({ ip: '8.8.8.8' }, (error, data, response) => {
  if (error) {
    console.error(error);
  } else {
    console.log(JSON.stringify(data, null, 2));
  }
});

Sample Response:

Response
1{
2  "ip": "8.8.8.8",
3  "location": {
4    "continent_code": "NA",
5    "continent_name": "North America",
6    "country_code2": "US",
7    "country_code3": "USA",
8    "country_name": "United States",
9    "country_name_official": "United States of America",
10    "country_capital": "Washington, D.C.",
11    "state_prov": "California",
12    "state_code": "US-CA",
13    "district": "Santa Clara",
14    "city": "Mountain View",
15    "zipcode": "94043-1351",
16    "latitude": "37.42240",
17    "longitude": "-122.08421",
18    "is_eu": false,
19    "country_flag": "https://ipgeolocation.io/static/flags/us_64.png",
20    "geoname_id": "6301403",
21    "country_emoji": "🇺🇸"
22  },
23  "country_metadata": {
24    "calling_code": "+1",
25    "tld": ".us",
26    "languages": [
27      "en-US",
28      "es-US",
29      "haw",
30      "fr"
31    ]
32  },
33  "currency": {
34    "code": "USD",
35    "name": "US Dollar",
36    "symbol": "$"
37  }
38}

Filtering Specific Fields from the Response (Use of exclude and fields ).

api.getIpGeolocation({
  ip: '8.8.4.4',
  fields: 'location',
  excludes: 'location.continent_code,location.continent_name'
}, (error, data, response) => {
  if (error) console.error(error);
  else console.log(JSON.stringify(data, null, 2));
});

Sample Response:

Response
1{
2  "ip": "8.8.4.4",
3  "location": {
4    "country_code2": "US",
5    "country_code3": "USA",
6    "country_name": "United States",
7    "country_name_official": "United States of America",
8    "country_capital": "Washington, D.C.",
9    "state_prov": "California",
10    "state_code": "US-CA",
11    "district": "Santa Clara",
12    "city": "Mountain View",
13    "zipcode": "94043-1351",
14    "latitude": "37.42240",
15    "longitude": "-122.08421",
16    "is_eu": false,
17    "country_flag": "https://ipgeolocation.io/static/flags/us_64.png",
18    "geoname_id": "6301403",
19    "country_emoji": "🇺🇸"
20  }
21}

2.Standard Plan Examples

I.Geolocation with Default Fields

api.getIpGeolocation({ ip: '8.8.8.8' }, (error, data) => {
  if (error) console.error(error);
  else console.log(JSON.stringify(data, null, 2));
});

Sample Response:

Response
1{
2  "ip": "8.8.8.8",
3  "location": {
4    "continent_code": "NA",
5    "continent_name": "North America",
6    "country_code2": "US",
7    "country_code3": "USA",
8    "country_name": "United States",
9    "country_name_official": "United States of America",
10    "country_capital": "Washington, D.C.",
11    "state_prov": "California",
12    "state_code": "US-CA",
13    "district": "Santa Clara",
14    "city": "Mountain View",
15    "zipcode": "94043-1351",
16    "latitude": "37.42240",
17    "longitude": "-122.08421",
18    "is_eu": false,
19    "country_flag": "https://ipgeolocation.io/static/flags/us_64.png",
20    "geoname_id": "6301403",
21    "country_emoji": "🇺🇸"
22  },
23  "country_metadata": {
24    "calling_code": "+1",
25    "tld": ".us",
26    "languages": [
27      "en-US",
28      "es-US",
29      "haw",
30      "fr"
31    ]
32  },
33  "network": {
34    "asn": {
35      "as_number": "AS15169",
36      "organization": "Google LLC",
37      "country": "US"
38    },
39    "company": {
40      "name": "Google LLC"
41    }
42  },
43  "currency": {
44    "code": "USD",
45    "name": "US Dollar",
46    "symbol": "$"
47  }
48}

3.Retrieving Geolocation Data in Multiple Languages

Here is an example to get the geolocation data for IP address '2001:4230:4890::1' in French language:

api.getIpGeolocation({
  ip: '2001:4230:4890::1',
  lang: 'fr'
}, (error, data) => {
  if (error) console.error(error);
  else console.log(JSON.stringify(data, null, 2));
});

Sample Response:

Response
1{
2  "ip": "2001:4230:4890:0:0:0:0:1",
3  "location": {
4    "continent_code": "AF",
5    "continent_name": "Afrique",
6    "country_code2": "MU",
7    "country_code3": "MUS",
8    "country_name": "Maurice",
9    "country_name_official": "",
10    "country_capital": "Port Louis",
11    "state_prov": "Wilhems des plaines",
12    "state_code": "MU-PW",
13    "district": "Quatre Bornes",
14    "city": "Quatre Bornes",
15    "zipcode": "72201",
16    "latitude": "-20.24304",
17    "longitude": "57.49631",
18    "is_eu": false,
19    "country_flag": "https://ipgeolocation.io/static/flags/mu_64.png",
20    "geoname_id": "1106777",
21    "country_emoji": "🇲🇺"
22  },
23  "country_metadata": {
24    "calling_code": "+230",
25    "tld": ".mu",
26    "languages": [
27      "en-MU",
28      "bho",
29      "fr"
30    ]
31  },
32  "network": {
33    "asn": {
34      "as_number": "AS0",
35      "organization": "",
36      "country": ""
37    },
38    "company": {
39      "name": "African Network Information Center AfriNIC Ltd"
40    }
41  },
42  "currency": {
43    "code": "MUR",
44    "name": "Mauritius Rupee",
45    "symbol": "₨"
46  }
47}

I.Include Hostname, Timezone, and User-Agent

api.getIpGeolocation({
  ip: '4.5.6.7',
  fields: 'location.country_name,location.country_capital',
  include: 'user_agent,time_zone,hostnameFallbackLive'
}, (error, data) => {
  if (error) console.error(error);
  else console.log(JSON.stringify(data, null, 2));
});

Sample Response:

Response
1{
2  "ip": "4.5.6.7",
3  "hostname": "4.5.6.7",
4  "location": {
5    "country_name": "United States",
6    "country_capital": "Washington, D.C."
7  },
8  "time_zone": {
9    "name": "America/Chicago",
10    "offset": -6,
11    "offset_with_dst": -5,
12    "current_time": "2025-07-11 04:50:39.537-0500",
13    "current_time_unix": 1752227439.537,
14    "is_dst": true,
15    "dst_savings": 1,
16    "dst_exists": true,
17    "dst_start": {
18      "utc_time": "2025-03-09 TIME 08",
19      "duration": "+1H",
20      "gap": true,
21      "date_time_after": "2025-03-09 TIME 03",
22      "date_time_before": "2025-03-09 TIME 02",
23      "overlap": false
24    },
25    "dst_end": {
26      "utc_time": "2025-11-02 TIME 07",
27      "duration": "-1H",
28      "gap": false,
29      "date_time_after": "2025-11-02 TIME 01",
30      "date_time_before": "2025-11-02 TIME 02",
31      "overlap": true
32    }
33  },
34  "user_agent": {
35    "user_agent_string": "Ipgeolocation/2.0/Javascript",
36    "name": "Ipgeolocation",
37    "type": "Special",
38    "version": "2.0",
39    "version_major": "2",
40    "device": {
41      "name": "Unknown",
42      "type": "Unknown",
43      "brand": "Unknown",
44      "cpu": "Unknown"
45    },
46    "engine": {
47      "name": "Unknown",
48      "type": "Unknown",
49      "version": "??",
50      "version_major": "??"
51    },
52    "operating_system": {
53      "name": "Unknown",
54      "type": "Unknown",
55      "version": "??",
56      "version_major": "??",
57      "build": "??"
58    }
59  }
60}
Note

The IP Geolocation API supports hostname lookup for all paid subscriptions. However, this is not included by default. To enable hostname resolution, use the include parameter with one of the following options:

  • hostname : Performs a quick lookup using the internal hostname database. If no match is found, the IP is returned as-is. This is fast but may produce incomplete results.
  • liveHostname : Queries live sources for accurate hostname resolution. This may increase response time.
  • hostnameFallbackLive : Attempts the internal database first, and falls back to live sources if no result is found. This option provides a balance of speed and reliability.

4.Advanced Plan Example

I.Include DMA, Abuse, and Security

api.getIpGeolocation({
  ip: '8.8.8.8',
  excludes: 'location.country_flag,location.country_emoji',
  include: 'dma,abuse,security'
}, (error, data) => {
  if (error) console.error(error);
  else console.log(JSON.stringify(data, null, 2));
});

Sample Response:

Response
1{
2  "ip": "8.8.8.8",
3  "location": {
4    "continent_code": "NA",
5    "continent_name": "North America",
6    "country_code2": "US",
7    "country_code3": "USA",
8    "country_name": "United States",
9    "country_name_official": "United States of America",
10    "country_capital": "Washington, D.C.",
11    "state_prov": "California",
12    "state_code": "US-CA",
13    "district": "Santa Clara",
14    "city": "Mountain View",
15    "zipcode": "94043-1351",
16    "latitude": "37.42240",
17    "longitude": "-122.08421",
18    "is_eu": false,
19    "geoname_id": "6301403",
20    "accuracy_radius": "",
21    "locality": "Mountain View",
22    "dma_code": "807"
23  },
24  "country_metadata": {
25    "calling_code": "+1",
26    "tld": ".us",
27    "languages": [
28      "en-US",
29      "es-US",
30      "haw",
31      "fr"
32    ]
33  },
34  "network": {
35    "asn": {
36      "as_number": "AS15169",
37      "organization": "Google LLC",
38      "country": "US",
39      "asn_name": "GOOGLE",
40      "type": "BUSINESS",
41      "domain": "about.google",
42      "date_allocated": "",
43      "allocation_status": "assigned",
44      "num_of_ipv4_routes": "984",
45      "num_of_ipv6_routes": "104",
46      "rir": "ARIN"
47    },
48    "connection_type": "",
49    "company": {
50      "name": "Google LLC",
51      "type": "Business",
52      "domain": "googlellc.com"
53    }
54  },
55  "currency": {
56    "code": "USD",
57    "name": "US Dollar",
58    "symbol": "$"
59  },
60  "security": {
61    "threat_score": 0,
62    "is_tor": false,
63    "is_proxy": false,
64    "proxy_type": "",
65    "proxy_provider": "",
66    "is_anonymous": false,
67    "is_known_attacker": false,
68    "is_spam": false,
69    "is_bot": false,
70    "is_cloud_provider": false,
71    "cloud_provider": ""
72  },
73  "abuse": {
74    "route": "8.8.8.0/24",
75    "country": "",
76    "handle": "ABUSE5250-ARIN",
77    "name": "Abuse",
78    "organization": "Abuse",
79    "role": "abuse",
80    "kind": "group",
81    "address": "1600 Amphitheatre Parkway\nMountain View\nCA\n94043\nUnited States",
82    "emails": [
83      "network-abuse@google.com"
84    ],
85    "phone_numbers": [
86      "+1-650-253-0000"
87    ]
88  }
89}

These examples demonstrate typical usage of the IP Geolocation API with different subscription tiers. Use fields to specify exactly which data to receive, include for optional data like security and user agent, and excludes to omit specific keys from the response.

Note

All features available in the Free plan are also included in the Standard and Advanced plans. Similarly, all features of the Standard plan are available in the Advanced plan.

5.Bulk IP Geolocation Examples

The SDK supports bulk IP geolocation using getBulkIpGeolocation() . This is available for Standard and Advanced plans. All parameters like fields , include , and excludes can be used in bulk requests.

const { BulkIPRequest } =  require('ip-geolocation-api-javascript-sdk');

const bulkRequest = new BulkIPRequest();
bulkRequest.ips = ['8.8.8.8', '1.1.1.1'];

api.getBulkIpGeolocation(bulkRequest, {
  fields: 'location.country_name,location.city',
  excludes: 'location.continent_code',
  include: 'security,timezone'
}, (error, data) => {
  if (error) console.error(error);
  else console.log(JSON.stringify(data, null, 2));
});

IP Security Examples

The getIpSecurityInfo() method lets you query threat intelligence, proxy/VPN detection, and risk metadata for IP addresses.

For full endpoint specifications, refer to the IP Security API documentation.

1.Get Security API Default Fields

const { APIClient, IPSecurityAPI } = require('ip-geolocation-api-javascript-sdk');

const client = APIClient.instance;
client.authentications['ApiKeyAuth'].apiKey = 'YOUR_API_KEY';

const api = new IPSecurityAPI(client);

api.getIpSecurityInfo({ ip: '2.56.188.34' }, (error, data) => {
  if (error) return console.error('API call failed:', error);
  console.log(JSON.stringify(data, null, 2));
});

Sample Response:

Response
1{
2  "ip": "2.56.188.34",
3  "security": {
4    "threat_score": 80,
5    "is_tor": false,
6    "is_proxy": true,
7    "proxy_type": "VPN",
8    "proxy_provider": "Nord VPN",
9    "is_anonymous": true,
10    "is_known_attacker": true,
11    "is_spam": false,
12    "is_bot": false,
13    "is_cloud_provider": true,
14    "cloud_provider": "Packethub S.A."
15  }
16}

2.Include Multiple Optional Fields

api.getIpSecurityInfo({
  ip: '2.56.188.34',
  include: 'location,network,currency,time_zone,user_agent,country_metadata,hostname'
}, (error, data) => {
  if (error) return console.error('API call failed:', error);
  console.log(JSON.stringify(data, null, 2));
});

Sample Response:

Response
1{
2  "ip": "2.56.188.34",
3  "hostname": "2.56.188.34",
4  "security": {
5    "threat_score": 80,
6    "is_tor": false,
7    "is_proxy": true,
8    "proxy_type": "VPN",
9    "proxy_provider": "Nord VPN",
10    "is_anonymous": true,
11    "is_known_attacker": true,
12    "is_spam": false,
13    "is_bot": false,
14    "is_cloud_provider": true,
15    "cloud_provider": "Packethub S.A."
16  },
17  "location": {
18    "continent_code": "NA",
19    "continent_name": "North America",
20    "country_code2": "US",
21    "country_code3": "USA",
22    "country_name": "United States",
23    "country_name_official": "United States of America",
24    "country_capital": "Washington, D.C.",
25    "state_prov": "Texas",
26    "state_code": "US-TX",
27    "district": "Dallas",
28    "city": "Dallas",
29    "zipcode": "75201",
30    "latitude": "32.77822",
31    "longitude": "-96.79512",
32    "is_eu": false,
33    "country_flag": "https://ipgeolocation.io/static/flags/us_64.png",
34    "geoname_id": "4684902",
35    "country_emoji": "🇺🇸"
36  },
37  "network": {
38    "asn": {
39      "as_number": "AS62240",
40      "organization": "Clouvider Limited",
41      "country": "GB"
42    },
43    "company": {
44      "name": "Packethub S.A."
45    }
46  },
47  "time_zone": {
48    "name": "America/Chicago",
49    "offset": -6,
50    "offset_with_dst": -5,
51    "current_time": "2025-07-16 11:00:50.605-0500",
52    "current_time_unix": 1752681650.605,
53    "is_dst": true,
54    "dst_savings": 1,
55    "dst_exists": true,
56    "dst_start": {
57      "utc_time": "2025-03-09 TIME 08",
58      "duration": "+1H",
59      "gap": true,
60      "date_time_after": "2025-03-09 TIME 03",
61      "date_time_before": "2025-03-09 TIME 02",
62      "overlap": false
63    },
64    "dst_end": {
65      "utc_time": "2025-11-02 TIME 07",
66      "duration": "-1H",
67      "gap": false,
68      "date_time_after": "2025-11-02 TIME 01",
69      "date_time_before": "2025-11-02 TIME 02",
70      "overlap": true
71    }
72  },
73  "user_agent": {
74    "user_agent_string": "Ipgeolocation/2.0/Javascript",
75    "name": "Ipgeolocation",
76    "type": "Special",
77    "version": "2.0",
78    "version_major": "2",
79    "device": {
80      "name": "Unknown",
81      "type": "Unknown",
82      "brand": "Unknown",
83      "cpu": "Unknown"
84    },
85    "engine": {
86      "name": "Unknown",
87      "type": "Unknown",
88      "version": "??",
89      "version_major": "??"
90    },
91    "operating_system": {
92      "name": "Unknown",
93      "type": "Unknown",
94      "version": "??",
95      "version_major": "??",
96      "build": "??"
97    }
98  },
99  "country_metadata": {
100    "calling_code": "+1",
101    "tld": ".us",
102    "languages": [
103      "en-US",
104      "es-US",
105      "haw",
106      "fr"
107    ]
108  },
109  "currency": {
110    "code": "USD",
111    "name": "US Dollar",
112    "symbol": "$"
113  }
114}
Note

You can get all the available fields in standard plan in combination with security data, when subscribed to security plan.

3.Request with Field Filtering

api.getIpSecurityInfo({
  ip: '195.154.221.54',
  fields: 'security.is_tor,security.is_proxy,security.is_bot,security.is_spam'
}, (error, data) => {
  if (error) return console.error('API call failed:', error);
  console.log(JSON.stringify(data, null, 2));
});

Sample Response:

Response
1{
2  "ip": "195.154.221.54",
3  "security": {
4    "is_tor": false,
5    "is_proxy": true,
6    "is_spam": false,
7    "is_bot": false
8  }
9}

4.Bulk IP Security Lookup

The SDK also supports bulk IP Security requests using the getBulkIpSecurityInfo() method. All parameters like fields , include , and excludes can also be used in bulk requests.

const { BulkIPRequest } = require('ip-geolocation-api-javascript-sdk');

const bulkRequest = new BulkIPRequest({ ips: ['2.56.188.34', '2.56.188.35'] });

api.getBulkIpSecurityInfo(bulkRequest, {
  include: 'location,network',
  fields: 'security.threat_score,location.country_name'
}, (error, data) => {
  if (error) return console.error('API call failed:', error);
  console.log(JSON.stringify(data, null, 2));
});

ASN API Examples

This section provides usage examples of the getAsnInfo() method from the SDK. These methods allow developers to retrieve detailed ASN-level network data either by ASN number or by IP address.

Note

ASN API is only available in the Advanced subscription plans.

Refer to the ASN API documentation for a detailed list of supported fields and behaviors.

1.Get ASN Information by IP Address

const { APIClient, ASNLookupAPI } = require('ip-geolocation-api-javascript-sdk');

const client = APIClient.instance;
client.authentications['ApiKeyAuth'].apiKey = 'YOUR_API_KEY';

const api = new ASNLookupAPI(client);

api.getAsnInfo(
  { ip: '8.8.8.8' }, // IP address
  (error, data, response) => {
    if (error) {
      console.error("API call failed:", error);
    } else {
      console.log(JSON.stringify(data, null, 2));
    }
  }
);

Sample Response:

Response
1{
2  "ip": "8.8.8.8",
3  "asn": {
4    "as_number": "AS15169",
5    "organization": "Google LLC",
6    "country": "US",
7    "asn_name": "GOOGLE",
8    "type": "BUSINESS",
9    "domain": "about.google",
10    "date_allocated": "",
11    "allocation_status": "assigned",
12    "num_of_ipv4_routes": 983,
13    "num_of_ipv6_routes": 104,
14    "rir": "ARIN"
15  }
16}

2.Get ASN Information by ASN Number

api.getAsnInfo(
  { asn: 15169 }, // ASN number
  (error, data, response) => {
    if (error) {
      console.error("API call failed:", error);
    } else {
      console.log(JSON.stringify(data, null, 2));
    }
  }
);

Sample Response:

Response
1{
2  "asn": {
3    "as_number": "AS15169",
4    "organization": "Google LLC",
5    "country": "US",
6    "asn_name": "GOOGLE",
7    "type": "BUSINESS",
8    "domain": "about.google",
9    "date_allocated": "",
10    "allocation_status": "assigned",
11    "num_of_ipv4_routes": 983,
12    "num_of_ipv6_routes": 104,
13    "rir": "ARIN"
14  }
15}

3.Combine All objects using Include

api.getAsnInfo(
  {
    asn: 12,
    include: 'peers,downstreams,upstreams,routes,whois_response'
  },
  (error, data, response) => {
    if (error) {
      console.error("API call failed:", error);
    } else {
      console.log(JSON.stringify(data, null, 2));
    }
  }
);

Sample Response:

Response
1{
2  "asn": {
3    "as_number": "AS12",
4    "organization": "New York University",
5    "country": "US",
6    "asn_name": "NYU-DOMAIN",
7    "type": "EDUCATION",
8    "domain": "nyu.edu",
9    "date_allocated": "",
10    "allocation_status": "assigned",
11    "num_of_ipv4_routes": 12,
12    "num_of_ipv6_routes": 1,
13    "rir": "ARIN",
14    "routes": [
15      "192.76.177.0/24",
16      "...",
17      "216.165.120.0/22"
18    ],
19    "upstreams": [
20      {
21        "as_number": "AS3269",
22        "description": "Telecom Italia S.p.A.",
23        "country": "IT"
24      },
25      "...",
26      {
27        "as_number": "AS137",
28        "description": "Consortium GARR",
29        "country": "IT"
30      }
31    ],
32    "downstreams": [
33      {
34        "as_number": "AS394666",
35        "description": "NYU Langone Health",
36        "country": "US"
37      },
38      {
39        "as_number": "AS54965",
40        "description": "Polytechnic Institute of NYU",
41        "country": "US"
42      }
43    ],
44    "peers": [
45      {
46        "as_number": "AS3269",
47        "description": "Telecom Italia S.p.A.",
48        "country": "IT"
49      },
50      "...",
51      {
52        "as_number": "AS54965",
53        "description": "Polytechnic Institute of NYU",
54        "country": "US"
55      }
56    ],
57    "whois_response": "<RAW-Whois-Response>"
58  }
59}

Abuse Contact API Examples

This section demonstrates how to use the getAbuseContactInfo() method of the SDK. This API helps security teams, hosting providers, and compliance professionals quickly identify the correct abuse reporting contacts for any IPv4 or IPv6 address.

You can retrieve data like the responsible organization, role, contact emails, phone numbers, and address to take appropriate mitigation action against abusive or malicious activity.

Note

Abuse Contact API is only available in the Advanced Plan.

Refer to the official Abuse Contact API documentation for details on all available fields.

1.Lookup Abuse Contact by IP

const { APIClient, AbuseContactAPI } = require('ip-geolocation-api-javascript-sdk');

const client = APIClient.instance;
client.authentications['ApiKeyAuth'].apiKey = 'YOUR_API_KEY';

const api = new AbuseContactAPI(client);

api.getAbuseContactInfo({
  ip: '1.0.0.0'
}, (error, data, response) => {
  if (error) {
    console.error('Exception when calling AbuseContactAPI->getAbuseContactInfo:', error);
  } else {
    console.log(JSON.stringify(data, null, 2));
  }
});

Sample Response:

Response
1{
2  "ip": "1.0.0.0",
3  "abuse": {
4    "route": "1.0.0.0/24",
5    "country": "AU",
6    "handle": "IRT-APNICRANDNET-AU",
7    "name": "IRT-APNICRANDNET-AU",
8    "organization": "",
9    "role": "abuse",
10    "kind": "group",
11    "address": "PO Box 3646\nSouth Brisbane, QLD 4101\nAustralia",
12    "emails": [
13      "helpdesk@apnic.net"
14    ],
15    "phone_numbers": [
16      "+61 7 3858 3100"
17    ]
18  }
19}

2.Lookup Abuse Contact with Specific Fields

api.getAbuseContactInfo({
  ip: '1.2.3.4',
  fields: 'abuse.role,abuse.emails'
}, (error, data, response) => {
  if (error) {
    console.error('Exception when calling AbuseContactAPI->getAbuseContactInfo:', error);
  } else {
    console.log(JSON.stringify(data, null, 2));
  }
});

Sample Response:

Response
1{
2  "ip": "1.2.3.4",
3  "abuse": {
4    "role": "abuse",
5    "emails": [
6      "helpdesk@apnic.net"
7    ]
8  }
9}

3.Lookup Abuse Contact while Excluding Fields

api.getAbuseContactInfo({
  ip: '9.9.9.9',
  excludes: 'abuse.handle,abuse.emails'
}, (error, data, response) => {
  if (error) {
    console.error('Exception when calling AbuseContactAPI->getAbuseContactInfo:', error);
  } else {
    console.log(JSON.stringify(data, null, 2));
  }
});

Sample Response:

Response
1{
2  "ip": "9.9.9.9",
3  "abuse": {
4    "route": "9.9.9.0/24",
5    "country": "",
6    "name": "Quad9 Abuse",
7    "organization": "Quad9 Abuse",
8    "role": "abuse",
9    "kind": "group",
10    "address": "1442 A Walnut Street Ste 501\nBerkeley\nCA\n94709\nUnited States",
11    "phone_numbers": [
12      "+1-415-831-3129"
13    ]
14  }
15}

Timezone API Examples

This section provides usage examples of the getTimezoneInfo() method from the JavaScript SDK, showcasing how to fetch timezone and time-related data using different query types — IP address, latitude/longitude, timezone ID, IATA code, ICAO code, or UN/LOCODE.

For full API specifications, refer to the Timezone API documentation.

1.Get Timezone by IP Address

const {APIClient, TimezoneAPI} = require('ip-geolocation-api-javascript-sdk');

const client = APIClient.instance;
client.authentications['ApiKeyAuth'].apiKey = 'YOUR_API_KEY';

const api = new TimezoneAPI();

api.getTimezoneInfo({
  ip: '8.8.8.8'
}, (error, data, response) => {
  if (error) {
    console.error('Exception when calling TimezoneAPI->getTimezoneInfo:', error);
  } else {
    console.log(JSON.stringify(data, null, 2));
  }
});

Sample Response:

Response
1{
2  "ip": "8.8.8.8",
3  "location": {
4    "continent_code": "NA",
5    "continent_name": "North America",
6    "country_code2": "US",
7    "country_code3": "USA",
8    "country_name": "United States",
9    "country_name_official": "United States of America",
10    "is_eu": false,
11    "state_prov": "California",
12    "state_code": "US-CA",
13    "district": "Santa Clara",
14    "city": "Mountain View",
15    "zipcode": "94043-1351",
16    "latitude": "37.42240",
17    "longitude": "-122.08421"
18  },
19  "time_zone": {
20    "name": "America/Los_Angeles",
21    "offset": -8,
22    "offset_with_dst": -7,
23    "date": "2025-07-17T00:00:00.000Z",
24    "date_time": "2025-07-17 04:14:57",
25    "date_time_txt": "Thursday, July 17, 2025 04:14:57",
26    "date_time_wti": "Thu, 17 Jul 2025 04:14:57 -0700",
27    "date_time_ymd": "2025-07-17T11:14:57.000Z",
28    "date_time_unix": 1752750897.094,
29    "time_24": "04:14:57",
30    "time_12": "04:14:57 AM",
31    "week": 29,
32    "month": 7,
33    "year": 2025,
34    "year_abbr": "25",
35    "is_dst": true,
36    "dst_savings": 1,
37    "dst_exists": true,
38    "dst_start": {
39      "utc_time": "2025-03-09 TIME 10",
40      "duration": "+1H",
41      "gap": true,
42      "date_time_after": "2025-03-09 TIME 03",
43      "date_time_before": "2025-03-09 TIME 02",
44      "overlap": false
45    },
46    "dst_end": {
47      "utc_time": "2025-11-02 TIME 09",
48      "duration": "-1H",
49      "gap": false,
50      "date_time_after": "2025-11-02 TIME 01",
51      "date_time_before": "2025-11-02 TIME 02",
52      "overlap": true
53    }
54  }
55}

2.Get Timezone by Timezone Name

api.getTimezoneInfo({
  tz: 'Europe/London'
}, (error, data, response) => {
  if (error) {
    console.error('Exception when calling TimezoneAPI->getTimezoneInfo:', error);
  } else {
    console.log(JSON.stringify(data, null, 2));
  }
});

Sample Response:

Response
1{
2  "time_zone": {
3    "name": "Europe/London",
4    "offset": 0,
5    "offset_with_dst": 1,
6    "date": "2025-07-17T00:00:00.000Z",
7    "date_time": "2025-07-17 12:17:33",
8    "date_time_txt": "Thursday, July 17, 2025 12:17:33",
9    "date_time_wti": "Thu, 17 Jul 2025 12:17:33 +0100",
10    "date_time_ymd": "2025-07-17T11:17:33.000Z",
11    "date_time_unix": 1752751053.019,
12    "time_24": "12:17:33",
13    "time_12": "12:17:33 PM",
14    "week": 29,
15    "month": 7,
16    "year": 2025,
17    "year_abbr": "25",
18    "is_dst": true,
19    "dst_savings": 1,
20    "dst_exists": true,
21    "dst_start": {
22      "utc_time": "2025-03-30 TIME 01",
23      "duration": "+1H",
24      "gap": true,
25      "date_time_after": "2025-03-30 TIME 02",
26      "date_time_before": "2025-03-30 TIME 01",
27      "overlap": false
28    },
29    "dst_end": {
30      "utc_time": "2025-10-26 TIME 01",
31      "duration": "-1H",
32      "gap": false,
33      "date_time_after": "2025-10-26 TIME 01",
34      "date_time_before": "2025-10-26 TIME 02",
35      "overlap": true
36    }
37  }
38}

3.Get Timezone from Any Address

api.getTimezoneInfo({
  location: 'Munich, Germany'
}, (error, data, response) => {
  if (error) {
    console.error('Exception when calling TimezoneAPI->getTimezoneInfo:', error);
  } else {
    console.log(JSON.stringify(data, null, 2));
  }
});

Sample Response:

Response
1{
2  "location": {
3    "location_string": "Munich, Germany",
4    "country_name": "Germany",
5    "state_prov": "Bavaria",
6    "city": "Munich",
7    "locality": "",
8    "latitude": "48.13711",
9    "longitude": "11.57538"
10  },
11  "time_zone": {
12    "name": "Europe/Berlin",
13    "offset": 1,
14    "offset_with_dst": 2,
15    "date": "2025-07-17T00:00:00.000Z",
16    "date_time": "2025-07-17 13:19:49",
17    "date_time_txt": "Thursday, July 17, 2025 13:19:49",
18    "date_time_wti": "Thu, 17 Jul 2025 13:19:49 +0200",
19    "date_time_ymd": "2025-07-17T11:19:49.000Z",
20    "date_time_unix": 1752751189.372,
21    "time_24": "13:19:49",
22    "time_12": "01:19:49 PM",
23    "week": 29,
24    "month": 7,
25    "year": 2025,
26    "year_abbr": "25",
27    "is_dst": true,
28    "dst_savings": 1,
29    "dst_exists": true,
30    "dst_start": {
31      "utc_time": "2025-03-30 TIME 01",
32      "duration": "+1H",
33      "gap": true,
34      "date_time_after": "2025-03-30 TIME 03",
35      "date_time_before": "2025-03-30 TIME 02",
36      "overlap": false
37    },
38    "dst_end": {
39      "utc_time": "2025-10-26 TIME 01",
40      "duration": "-1H",
41      "gap": false,
42      "date_time_after": "2025-10-26 TIME 02",
43      "date_time_before": "2025-10-26 TIME 03",
44      "overlap": true
45    }
46  }
47}

4.Get Timezone from Location Coordinates

api.getTimezoneInfo({
  lat: 48.8566,
  _long: 2.3522
}, (error, data, response) => {
  if (error) {
    console.error('Exception when calling TimezoneAPI->getTimezoneInfo:', error);
  } else {
    console.log(JSON.stringify(data, null, 2));
  }
});

Sample Response:

Response
1{
2  "time_zone": {
3    "name": "Europe/Paris",
4    "offset": 1,
5    "offset_with_dst": 2,
6    "date": "2025-07-17T00:00:00.000Z",
7    "date_time": "2025-07-17 13:31:58",
8    "date_time_txt": "Thursday, July 17, 2025 13:31:58",
9    "date_time_wti": "Thu, 17 Jul 2025 13:31:58 +0200",
10    "date_time_ymd": "2025-07-17T11:31:58.000Z",
11    "date_time_unix": 1752751918.965,
12    "time_24": "13:31:58",
13    "time_12": "01:31:58 PM",
14    "week": 29,
15    "month": 7,
16    "year": 2025,
17    "year_abbr": "25",
18    "is_dst": true,
19    "dst_savings": 1,
20    "dst_exists": true,
21    "dst_start": {
22      "utc_time": "2025-03-30 TIME 01",
23      "duration": "+1H",
24      "gap": true,
25      "date_time_after": "2025-03-30 TIME 03",
26      "date_time_before": "2025-03-30 TIME 02",
27      "overlap": false
28    },
29    "dst_end": {
30      "utc_time": "2025-10-26 TIME 01",
31      "duration": "-1H",
32      "gap": false,
33      "date_time_after": "2025-10-26 TIME 02",
34      "date_time_before": "2025-10-26 TIME 03",
35      "overlap": true
36    }
37  }
38}

5.Get Timezone and Airport Details from IATA Code

api.getTimezoneInfo({
  iataDode: 'ZRH'
}, (error, data, response) => {
  if (error) {
    console.error('Exception when calling TimezoneAPI->getTimezoneInfo:', error);
  } else {
    console.log(JSON.stringify(data, null, 2));
  }
});

Sample Response:

Response
1{
2  "airport_details": {
3    "type": "large_airport",
4    "name": "Zurich Airport",
5    "latitude": "47.45806",
6    "longitude": "8.54806",
7    "elevation_ft": 1417,
8    "continent_code": "EU",
9    "country_code": "CH",
10    "state_code": "CH-ZH",
11    "city": "Zurich",
12    "iata_code": "ZRH",
13    "icao_code": "LSZH",
14    "faa_code": ""
15  },
16  "time_zone": {
17    "name": "Europe/Zurich",
18    "offset": 1,
19    "offset_with_dst": 2,
20    "date": "2025-07-17T00:00:00.000Z",
21    "date_time": "2025-07-17 13:43:56",
22    "date_time_txt": "Thursday, July 17, 2025 13:43:56",
23    "date_time_wti": "Thu, 17 Jul 2025 13:43:56 +0200",
24    "date_time_ymd": "2025-07-17T11:43:56.000Z",
25    "date_time_unix": 1752752636.652,
26    "time_24": "13:43:56",
27    "time_12": "01:43:56 PM",
28    "week": 29,
29    "month": 7,
30    "year": 2025,
31    "year_abbr": "25",
32    "is_dst": true,
33    "dst_savings": 1,
34    "dst_exists": true,
35    "dst_start": {
36      "utc_time": "2025-03-30 TIME 01",
37      "duration": "+1H",
38      "gap": true,
39      "date_time_after": "2025-03-30 TIME 03",
40      "date_time_before": "2025-03-30 TIME 02",
41      "overlap": false
42    },
43    "dst_end": {
44      "utc_time": "2025-10-26 TIME 01",
45      "duration": "-1H",
46      "gap": false,
47      "date_time_after": "2025-10-26 TIME 02",
48      "date_time_before": "2025-10-26 TIME 03",
49      "overlap": true
50    }
51  }
52}

You can also fetch Airport Details and Timezone using any ICAO code by passing the icaoCode parameter.

6.Get Timezone and City Details from UN/LOCODE

api.getTimezoneInfo({
  loCode: 'ESBCN'
}, (error, data, response) => {
  if (error) {
    console.error('Exception when calling TimezoneAPI->getTimezoneInfo:', error);
  } else {
    console.log(JSON.stringify(data, null, 2));
  }
});

Sample Response:

Response
1{
2  "lo_code_details": {
3    "lo_code": "ESBCN",
4    "city": "Barcelona",
5    "state_code": "",
6    "country_code": "ES",
7    "country_name": "",
8    "location_type": "Port, Rail Terminal, Road Terminal, Airport, Postal Exchange",
9    "latitude": "41.38289",
10    "longitude": "2.17743"
11  },
12  "time_zone": {
13    "name": "Europe/Madrid",
14    "offset": 1,
15    "offset_with_dst": 2,
16    "date": "2025-07-17T00:00:00.000Z",
17    "date_time": "2025-07-17 14:59:43",
18    "date_time_txt": "Thursday, July 17, 2025 14:59:43",
19    "date_time_wti": "Thu, 17 Jul 2025 14:59:43 +0200",
20    "date_time_ymd": "2025-07-17T12:59:43.000Z",
21    "date_time_unix": 1752757183.827,
22    "time_24": "14:59:43",
23    "time_12": "02:59:43 PM",
24    "week": 29,
25    "month": 7,
26    "year": 2025,
27    "year_abbr": "25",
28    "is_dst": true,
29    "dst_savings": 1,
30    "dst_exists": true,
31    "dst_start": {
32      "utc_time": "2025-03-30 TIME 01",
33      "duration": "+1H",
34      "gap": true,
35      "date_time_after": "2025-03-30 TIME 03",
36      "date_time_before": "2025-03-30 TIME 02",
37      "overlap": false
38    },
39    "dst_end": {
40      "utc_time": "2025-10-26 TIME 01",
41      "duration": "-1H",
42      "gap": false,
43      "date_time_after": "2025-10-26 TIME 02",
44      "date_time_before": "2025-10-26 TIME 03",
45      "overlap": true
46    }
47  }
48}

Timezone Converter API Examples

This section provides usage examples of the convertTimeBetweenTimezones() method from the SDK. The Timezone Converter API allows you to convert a specific time from one timezone to another using timezone identifiers and optional date/time inputs.

For more details, refer to the Timezone Converter API documentation.

1.Convert Current Time from One Timezone to Another

const { TimeConversionAPI, APIClient } = require('ip-geolocation-api-javascript-sdk');

const apiClient = new APIClient();
const api = new TimeConversionAPI(apiClient);

const opts = {
  time: "2024-12-08 11:00",
  tzFrom: "America/New_York",
  tzTo: "Asia/Tokyo"
};

api.convertTimeBetweenTimezones(opts, (error, data, response) => {
  if (error) {
    console.error('Exception when calling TimeConversionAPI->convertTimeBetweenTimezones:', error);
  } else {
    console.log(JSON.stringify(data, null, 2));
  }
});

Sample Response:

Response
1{
2  "original_time": "2024-12-08T06:00:00.000Z",
3  "converted_time": "2024-12-08T20:00:00.000Z",
4  "diff_hour": 14,
5  "diff_min": 840
6}

You can convert time from any timezone to another using:

  • Coordinate (latitude & longitude)
  • Locations (city or address)
  • IATA codes
  • ICAO codes
  • UN/LOCODE

Simply provide the appropriate source and target parameters in the method.

User Agent API Examples

This section provides usage examples of the getUserAgentDetails() and parseBulkUserAgentStrings() methods from the JavaScript SDK. The User Agent API extracts and classifies information from user agent strings, including browser, engine, device, OS, and type metadata.

For full explanation, visit the User Agent API documentation.

1.Parse a Basic User Agent String

const  { UserAgentAPI } = require('ip-geolocation-api-javascript-sdk');
const api = new UserAgentAPI();

const opts = {
  userAgent: "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/125.0.0.0 Safari/537.36"
};

api.getUserAgentDetails(opts, (error, data, response) => {
  if (error) {
    console.error('Exception when calling UserAgentAPI->getUserAgentDetails:', error);
  } else {
    console.log(JSON.stringify(data, null, 2));
  }
});

Sample Response:

Response
1{
2  "user_agent_string": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/125.0.0.0 Safari/537.36",
3  "name": "Chrome",
4  "type": "Browser",
5  "version": "125",
6  "version_major": "125",
7  "device": {
8    "name": "Desktop",
9    "type": "Desktop",
10    "brand": "Unknown",
11    "cpu": "Intel x86_64"
12  },
13  "engine": {
14    "name": "Blink",
15    "type": "Browser",
16    "version": "125",
17    "version_major": "125"
18  },
19  "operating_system": {
20    "name": "Windows NT",
21    "type": "Desktop",
22    "version": "??",
23    "version_major": "??",
24    "build": "??"
25  }
26}
Tip

If you don’t pass any userAgent string, the API will return data of the device's current User-Agent automatically.

2.Bulk User Agent Parsing Example

The SDK also supports bulk User Agent parsing using the parseBulkUserAgentStrings() method. This allows parsing multiple user agent strings in a single request. All fields available in single-user-agent parsing are returned per entry.

Note

Bulk User Agent API is only available for paid plans.

const { UserAgentAPI } = require('ip-geolocation-api-javascript-sdk');
const api = new UserAgentAPI();

const requestBody = {
  ua_strings: [
    "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/125.0.0.0 Safari/537.36",
    "Mozilla/5.0 (iPhone; CPU iPhone OS 16_0 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/16.0 Mobile/15E148 Safari/604.1"
  ]
};

const opts = {
  BulkUserAgentRequest: requestBody
};

apiInstance.parseBulkUserAgentStrings(opts, (error, data, response) => {
  if (error) {
    console.error('Exception when calling UserAgentAPI->parseBulkUserAgentStrings:', error);
  } else {
    console.log(JSON.stringify(data, null, 2));
  }
});

Astronomy API Examples

This section provides usage examples of the getAstronomyDetails() method from the SDK, allowing developers to fetch sun and moon timings and position data based on coordinates, IP, or location string.

Refer to the official Astronomy API documentation for more details.

1.Lookup Astronomy API by Coordinates

const { APIClient, AstronomyAPI } = require('ip-geolocation-api-javascript-sdk');

const client = new APIClient('YOUR_API_KEY');
const api = new AstronomyAPI(client);

const options = {
  lat: '40.7128',
  _long: '-74.0060'
};

api.getAstronomyDetails(options, (error, data, response) => {
  if (error) console.error('Exception when calling AstronomyAPI->getAstronomyDetails:', error);
  else console.log(JSON.stringify(data, null, 2));
});

Sample Response:

Response
1{
2  "location": {
3    "country_name": "",
4    "state_prov": "New York",
5    "city": "New York",
6    "locality": "",
7    "latitude": "40.71280",
8    "longitude": "-74.00600",
9    "elevation": "6"
10  },
11  "astronomy": {
12    "date": "2025-07-22",
13    "current_time": "12:08:03.637",
14    "mid_night": "01:02",
15    "night_end": "03:48",
16    "morning": {
17      "astronomical_twilight_begin": "03:48",
18      "astronomical_twilight_end": "04:32",
19      "nautical_twilight_begin": "04:32",
20      "nautical_twilight_end": "05:12",
21      "civil_twilight_begin": "05:12",
22      "civil_twilight_end": "05:43",
23      "blue_hour_begin": "04:59",
24      "blue_hour_end": "05:24",
25      "golden_hour_begin": "05:24",
26      "golden_hour_end": "06:23"
27    },
28    "sunrise": "05:43",
29    "sunset": "20:21",
30    "evening": {
31      "golden_hour_begin": "19:41",
32      "golden_hour_end": "20:40",
33      "blue_hour_begin": "20:40",
34      "blue_hour_end": "21:05",
35      "civil_twilight_begin": "20:21",
36      "civil_twilight_end": "20:52",
37      "nautical_twilight_begin": "20:52",
38      "nautical_twilight_end": "21:31",
39      "astronomical_twilight_begin": "21:31",
40      "astronomical_twilight_end": "22:16"
41    },
42    "night_begin": "22:16",
43    "sun_status": "-",
44    "solar_noon": "13:02",
45    "day_length": "14:37",
46    "sun_altitude": 66.36171104779359,
47    "sun_distance": 152012050.7566263,
48    "sun_azimuth": 146.51841856976972,
49    "moon_phase": "WANING_CRESCENT",
50    "moonrise": "02:48",
51    "moonset": "19:10",
52    "moon_status": "-",
53    "moon_altitude": 71.91067852938512,
54    "moon_distance": 370332.8633592859,
55    "moon_azimuth": 232.18896241301334,
56    "moon_parallactic_angle": 42.90572861876801,
57    "moon_illumination_percentage": "-5.82",
58    "moon_angle": 332.0715969163789
59  }
60}

2.Lookup Astronomy API by IP Address

const options = {
  ip: '8.8.8.8'
};

api.getAstronomyDetails(options, (error, data, response) => {
  if (error) console.error('Exception when calling AstronomyAPI->getAstronomyDetails:', error);
  else console.log(JSON.stringify(data, null, 2));
});

Sample Response:

Response
1{
2  "ip": "8.8.8.8",
3  "location": {
4    "continent_code": "NA",
5    "continent_name": "North America",
6    "country_code2": "US",
7    "country_code3": "USA",
8    "country_name": "United States",
9    "country_name_official": "United States of America",
10    "is_eu": false,
11    "state_prov": "California",
12    "state_code": "US-CA",
13    "district": "Santa Clara",
14    "city": "Mountain View",
15    "locality": "Charleston Terrace",
16    "zipcode": "94043-1351",
17    "latitude": "37.42240",
18    "longitude": "-122.08421",
19    "elevation": "3"
20  },
21  "astronomy": {
22    "date": "2025-07-22",
23    "current_time": "09:08:38.573",
24    "mid_night": "01:15",
25    "night_end": "04:18",
26    "morning": {
27      "astronomical_twilight_begin": "04:18",
28      "astronomical_twilight_end": "04:58",
29      "nautical_twilight_begin": "04:58",
30      "nautical_twilight_end": "05:35",
31      "civil_twilight_begin": "05:35",
32      "civil_twilight_end": "06:04",
33      "blue_hour_begin": "05:23",
34      "blue_hour_end": "05:47",
35      "golden_hour_begin": "05:47",
36      "golden_hour_end": "06:42"
37    },
38    "sunrise": "06:04",
39    "sunset": "20:24",
40    "evening": {
41      "golden_hour_begin": "19:46",
42      "golden_hour_end": "20:42",
43      "blue_hour_begin": "20:42",
44      "blue_hour_end": "21:05",
45      "civil_twilight_begin": "20:24",
46      "civil_twilight_end": "20:54",
47      "nautical_twilight_begin": "20:54",
48      "nautical_twilight_end": "21:30",
49      "astronomical_twilight_begin": "21:30",
50      "astronomical_twilight_end": "22:10"
51    },
52    "night_begin": "22:10",
53    "sun_status": "-",
54    "solar_noon": "13:14",
55    "day_length": "14:20",
56    "sun_altitude": 34.34803129267899,
57    "sun_distance": 152012050.75662628,
58    "sun_azimuth": 89.8970525672089,
59    "moon_phase": "WANING_CRESCENT",
60    "moonrise": "03:23",
61    "moonset": "19:16",
62    "moon_status": "-",
63    "moon_altitude": 62.034455712206615,
64    "moon_distance": 370333.6185030786,
65    "moon_azimuth": 99.42513011330385,
66    "moon_parallactic_angle": -62.958244692944554,
67    "moon_illumination_percentage": "-5.82",
68    "moon_angle": 332.0769921001466
69  }
70}

3.Lookup Astronomy API by Location String

const options = {
  location: 'Milan, Italy'
};

api.getAstronomyDetails(options, (error, data, response) => {
  if (error) console.error('Exception when calling AstronomyAPI->getAstronomyDetails:', error);
  else console.log(JSON.stringify(data, null, 2));
});

Sample Response:

Response
1{
2  "location": {
3    "location_string": "Milan, Italy",
4    "country_name": "Italy",
5    "state_prov": "Lombardy",
6    "city": "Milan",
7    "locality": "",
8    "latitude": "45.46419",
9    "longitude": "9.18963",
10    "elevation": "122"
11  },
12  "astronomy": {
13    "date": "2025-07-22",
14    "current_time": "18:09:10.992",
15    "mid_night": "01:29",
16    "night_end": "03:39",
17    "morning": {
18      "astronomical_twilight_begin": "03:39",
19      "astronomical_twilight_end": "04:35",
20      "nautical_twilight_begin": "04:35",
21      "nautical_twilight_end": "05:21",
22      "civil_twilight_begin": "05:21",
23      "civil_twilight_end": "05:54",
24      "blue_hour_begin": "05:06",
25      "blue_hour_end": "05:35",
26      "golden_hour_begin": "05:35",
27      "golden_hour_end": "06:40"
28    },
29    "sunrise": "05:54",
30    "sunset": "21:04",
31    "evening": {
32      "golden_hour_begin": "20:19",
33      "golden_hour_end": "21:24",
34      "blue_hour_begin": "21:24",
35      "blue_hour_end": "21:52",
36      "civil_twilight_begin": "21:04",
37      "civil_twilight_end": "21:38",
38      "nautical_twilight_begin": "21:38",
39      "nautical_twilight_end": "22:23",
40      "astronomical_twilight_begin": "22:23",
41      "astronomical_twilight_end": "23:18"
42    },
43    "night_begin": "23:18",
44    "sun_status": "-",
45    "solar_noon": "13:29",
46    "day_length": "15:10",
47    "sun_altitude": 28.169856679888845,
48    "sun_distance": 152012050.75662634,
49    "sun_azimuth": 270.6983052183797,
50    "moon_phase": "WANING_CRESCENT",
51    "moonrise": "02:36",
52    "moonset": "19:49",
53    "moon_status": "-",
54    "moon_altitude": 13.689479853567155,
55    "moon_distance": 370334.31938040146,
56    "moon_azimuth": 296.84370445526883,
57    "moon_parallactic_angle": 45.350334161659966,
58    "moon_illumination_percentage": "-5.82",
59    "moon_angle": 332.08199856245204
60  }
61}

4.Lookup Astronomy API for Specific Date

const options = {
  lat: '-27.47',
  _long: '153.02',
  date: '2025-01-01'
};

api.getAstronomyDetails(options, (error, data, response) => {
  if (error) console.error('Exception when calling AstronomyAPI->getAstronomyDetails:', error);
  else console.log(JSON.stringify(data, null, 2));
});

Sample Response:

Response
1{
2  "location": {
3    "country_name": "Australia",
4    "state_prov": "Queensland",
5    "city": "Brisbane",
6    "locality": "Brisbane",
7    "latitude": "-27.47000",
8    "longitude": "153.02000",
9    "elevation": ""
10  },
11  "astronomy": {
12    "date": "2025-01-01",
13    "current_time": "02:09:51.517",
14    "mid_night": "23:51",
15    "night_end": "03:24",
16    "morning": {
17      "astronomical_twilight_begin": "03:24",
18      "astronomical_twilight_end": "03:57",
19      "nautical_twilight_begin": "03:57",
20      "nautical_twilight_end": "04:29",
21      "civil_twilight_begin": "04:29",
22      "civil_twilight_end": "04:56",
23      "blue_hour_begin": "04:19",
24      "blue_hour_end": "04:40",
25      "golden_hour_begin": "04:40",
26      "golden_hour_end": "05:30"
27    },
28    "sunrise": "04:56",
29    "sunset": "18:46",
30    "evening": {
31      "golden_hour_begin": "18:12",
32      "golden_hour_end": "19:02",
33      "blue_hour_begin": "19:02",
34      "blue_hour_end": "19:23",
35      "civil_twilight_begin": "18:46",
36      "civil_twilight_end": "19:13",
37      "nautical_twilight_begin": "19:13",
38      "nautical_twilight_end": "19:45",
39      "astronomical_twilight_begin": "19:45",
40      "astronomical_twilight_end": "20:18"
41    },
42    "night_begin": "20:18",
43    "sun_status": "-",
44    "solar_noon": "11:51",
45    "day_length": "13:50",
46    "sun_altitude": -29.4286928132231,
47    "sun_distance": 147102938.88036567,
48    "sun_azimuth": 143.06960395892196,
49    "moon_phase": "NEW_MOON",
50    "moonrise": "05:42",
51    "moonset": "20:08",
52    "moon_status": "-",
53    "moon_altitude": -31.0476016259822,
54    "moon_distance": 383086.6727028855,
55    "moon_azimuth": 154.73430237040986,
56    "moon_parallactic_angle": -154.91634180109617,
57    "moon_illumination_percentage": "0.62",
58    "moon_angle": 9.03930980357242
59  }
60}

5.Lookup Location info in Different Language

You can also get Astronomy Data in other languages. This feature is only available for paid subscriptions.

const options = {
  ip: '1.1.1.1',
  lang: 'fr'
};

api.getAstronomyDetails(options, (error, data, response) => {
  if (error) console.error('Exception when calling AstronomyAPI->getAstronomyDetails:', error);
  else console.log(JSON.stringify(data, null, 2));
});

Sample Response:

Response
1{
2  "ip": "1.1.1.1",
3  "location": {
4    "continent_code": "OC",
5    "continent_name": "Océanie",
6    "country_code2": "AU",
7    "country_code3": "AUS",
8    "country_name": "Australie",
9    "country_name_official": "",
10    "is_eu": false,
11    "state_prov": "Queensland",
12    "state_code": "AU-QLD",
13    "district": "Brisbane",
14    "city": "Brisbane Sud",
15    "locality": "",
16    "zipcode": "4101",
17    "latitude": "-27.47306",
18    "longitude": "153.01421",
19    "elevation": ""
20  },
21  "astronomy": {
22    "date": "2025-07-23",
23    "current_time": "02:10:35.820",
24    "...": "",
25    "moon_angle": 332.095098449164
26  }
27}

Models

Subscribe Our Newsletter

Get the latest in geolocation tech, straight to your inbox.