Package Exports
- fetchipinfo
- fetchipinfo/index.js
This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (fetchipinfo) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.
Readme
FETCH IP Info
Simple, lightweight client for GEO IP Lookups. Get comprehensive geolocation, ISP, timezone, and network data for any IP address with just one line of code.
Installation
npm install fetchipinfoGetting Started
- Get your API key: Create a free account at bestipapi.com/register to get your API key
- Install the package:
npm install fetchipinfo - Start using: Configure your API key and make calls
Quick Start
const IPMonster = require('fetchipinfo');
// Configure your API key (do this once)
IPMonster.configure({ apiKey: 'your-api-key-here' });
// Validate IP addresses
console.log(IPMonster.validate('192.168.1.1')); // true
console.log(IPMonster.validate('invalid-ip')); // false
// Look up IP enrichment data
const data = await IPMonster.lookup('8.8.8.8');
console.log(data);Configuration
Method 1: Configure programmatically
IPMonster.configure({
apiKey: 'your-api-key',
baseUrl: 'https://api.bestipapi.com/query', // optional
timeout: 5000 // optional, in milliseconds
});Method 2: Environment variable
export IPMONSTER_API_KEY=your-api-keyAPI Reference
IPMonster.validate(ip)
Validates IP address format (both IPv4 and IPv6).
IPMonster.validate('192.168.1.1'); // true
IPMonster.validate('2001:db8::1'); // true
IPMonster.validate('invalid'); // falseParameters:
ip(string): IP address to validate
Returns: boolean
IPMonster.lookup(ip, [options])
Look up enrichment data for a single IP address.
const result = await IPMonster.lookup('8.8.8.8');
// Example response:
{
"ip_address": "8.8.8.8",
"ip_type": "IPv4",
"network": "8.8.8.0/24",
"latitude": 37.751,
"longitude": -97.822,
"postal_code": null,
"accuracy_radius": 1000,
"city_name": null,
"country_name": "United States",
"country_iso_code": "US",
"subdivision_1_name": null,
"subdivision_1_iso_code": null,
"subdivision_2_name": null,
"continent_name": "North America",
"continent_code": "NA",
"time_zone": "America/Chicago",
"time_zone_offset": -5,
"is_in_european_union": false,
"currency_code": "USD",
"currency_name": "US Dollar",
"primary_language_code": "EN",
"primary_language_name": "English",
"isp": "Google LLC",
"isp_name": "Google LLC",
"asn": 15169,
"aso": "GOOGLE",
"mobile_country_code": null,
"mobile_network_code": null,
"tor_detected": false
}Parameters:
ip(string): IP address to lookupoptions(object, optional): Request optionsapiKey(string): API key overridebaseUrl(string): API base URL overridetimeout(number): Request timeout in millisecondsoutput(string): Response format ('json', 'xml', 'plain')
Returns: Promise<Object> - Enrichment data
IPMonster.batchLookup(ips, [options])
Look up multiple IP addresses in a single request (maximum 300 IPs).
const results = await IPMonster.batchLookup([
'8.8.8.8',
'1.1.1.1',
'192.168.1.1'
]);
// Example response:
{
"results": [
{
"ip_address": "8.8.8.8",
"ip_type": "IPv4",
"country_name": "United States",
"city_name": null,
// ... full enrichment data
},
{
"ip_address": "192.168.1.1",
"error": "No location data found for this IP address",
"error_code": "NOT_FOUND"
}
],
"summary": {
"total_processed": 3,
"successful": 2,
"errors": 1,
"skipped": 0
}
}Parameters:
ips(string[]): Array of IP addresses (max 300)options(object, optional): Same as lookup options plus:output(string): Response format ('json', 'xml', 'text', 'plain')
Returns: Promise<Object> - Object with results array and summary
Response Fields
| Field | Type | Description |
|---|---|---|
ip_address |
string | The queried IP address |
ip_type |
string | IP version (IPv4 or IPv6) |
network |
string | Network range in CIDR notation |
latitude |
number | Geographic latitude coordinate |
longitude |
number | Geographic longitude coordinate |
postal_code |
string|null | Postal/ZIP code |
accuracy_radius |
number | Accuracy radius in kilometers |
city_name |
string|null | City name |
country_name |
string | Country name |
country_iso_code |
string | ISO 3166-1 alpha-2 country code |
subdivision_1_name |
string|null | State/province/region name |
subdivision_1_iso_code |
string|null | State/province/region ISO code |
subdivision_2_name |
string|null | Secondary subdivision name |
continent_name |
string | Continent name |
continent_code |
string | Two-letter continent code |
time_zone |
string | IANA timezone identifier |
time_zone_offset |
number | UTC timezone offset in hours |
is_in_european_union |
boolean | Whether IP is in European Union |
currency_code |
string | ISO 4217 currency code |
currency_name |
string | Currency name |
primary_language_code |
string | ISO 639-1 language code |
primary_language_name |
string | Primary language name |
isp |
string | Internet Service Provider name |
asn |
number | Autonomous System Number |
aso |
string | Autonomous System Organization |
mobile_country_code |
string|null | Mobile Country Code (for cellular networks) |
mobile_network_code |
string|null | Mobile Network Code (for cellular networks) |
tor_detected |
boolean | Whether the IP is associated with Tor network |
Error Handling
The package throws descriptive errors for various scenarios:
try {
const result = await IPMonster.lookup('8.8.8.8');
} catch (error) {
console.error(error.message);
// Possible errors:
// - "Invalid IP address format"
// - "API key not configured"
// - "Request timeout after 5000ms"
// - "IP Monster API error: Invalid API key"
// - "IP Monster API error: Rate limit exceeded"
}Requirements
- Node.js 18+ (for built-in fetch support)
- IP Monster API key
Examples
Basic Usage
const IPMonster = require('ipmonster');
IPMonster.configure({ apiKey: process.env.IPMONSTER_API_KEY });
async function checkIP(ip) {
if (!IPMonster.validate(ip)) {
console.log('Invalid IP address');
return;
}
try {
const data = await IPMonster.lookup(ip);
console.log(`${ip} is from ${data.city_name || 'Unknown City'}, ${data.country_name}`);
console.log(`ISP: ${data.isp}, Timezone: ${data.time_zone}`);
} catch (error) {
console.error('Lookup failed:', error.message);
}
}
checkIP('8.8.8.8');Batch Processing
async function analyzeIPs(ipList) {
const validIPs = ipList.filter(ip => IPMonster.validate(ip));
if (validIPs.length === 0) {
console.log('No valid IPs found');
return;
}
try {
const response = await IPMonster.batchLookup(validIPs);
console.log(`Processed ${response.summary.total_processed} IPs`);
console.log(`Successful: ${response.summary.successful}, Errors: ${response.summary.errors}`);
response.results.forEach(result => {
if (result.error) {
console.log(`${result.ip_address}: Error - ${result.error}`);
} else {
console.log(`${result.ip_address}: ${result.country_name} (${result.isp})`);
}
});
} catch (error) {
console.error('Batch lookup failed:', error.message);
}
}
analyzeIPs(['8.8.8.8', '1.1.1.1', '192.168.1.1']);Custom Output Format
// Get XML response
const xmlResult = await IPMonster.lookup('8.8.8.8', { output: 'xml' });
// Get plain text response
const plainResult = await IPMonster.lookup('8.8.8.8', { output: 'plain' });Custom Configuration
// Use custom timeout and base URL
const result = await IPMonster.lookup('8.8.8.8', {
timeout: 10000,
baseUrl: 'https://custom-api.bestipapi.com/query'
});Processing Large Datasets
async function processLargeIPList(allIPs) {
const batchSize = 300; // API maximum
const results = [];
for (let i = 0; i < allIPs.length; i += batchSize) {
const batch = allIPs.slice(i, i + batchSize);
const validBatch = batch.filter(ip => IPMonster.validate(ip));
if (validBatch.length > 0) {
try {
const response = await IPMonster.batchLookup(validBatch);
results.push(...response.results);
// Add delay to respect rate limits
await new Promise(resolve => setTimeout(resolve, 1000));
} catch (error) {
console.error(`Batch ${i / batchSize + 1} failed:`, error.message);
}
}
}
return results;
}License
MIT