IPLocate - IP address geolocation and threat detection


A Javascript/Typescript client for the IPLocate.io geolocation API. Look up detailed geolocation and threat intelligence data for any IP address:

- IP geolocation: IP to country, IP to city, IP to region/state, coordinates, timezone, postal code
- ASN information: Internet service provider, network details, routing information
- Privacy & threat detection: VPN, proxy, Tor, hosting provider detection
- Company information: Business details associated with IP addresses - company name, domain, type (ISP/hosting/education/government/business)
- Abuse contact: Network abuse reporting information
- Hosting detection: Cloud provider and hosting service detection using our proprietary hosting detection engine

See what information we can provide for your IP address.

Getting started

You can make 1,000 free requests per day with a free account. For higher plans, check out API pricing.

$3

``bash
yarn add node-iplocate


or

npm install node-iplocate

or

pnpm add node-iplocate
`

$3

`javascript
import IPLocate from 'node-iplocate';
// or: const IPLocate = require('node-iplocate').default;

// Create a client with your API key
// Get your free API key from https://iplocate.io/signup
const client = new IPLocate('your-api-key');

// Look up an IP address
const result = await client.lookup('8.8.8.8');

console.log(IP: ${result.ip});
if (result.country) {
console.log(Country: ${result.country});
}
if (result.city) {
console.log(City: ${result.city});
}

// Check privacy flags
console.log(Is VPN: ${result.privacy.is_vpn});
console.log(Is Proxy: ${result.privacy.is_proxy});
`

$3

`typescript
// Look up your own IP address (no IP parameter)
const result = await client.lookupSelf();
console.log(Your IP: ${result.ip});
`

$3

`typescript
const result = await client.lookup('203.0.113.1');
console.log(Country: ${result.country} (${result.country_code}));
`

$3

`typescript
const result = await client.lookup('203.0.113.1');
console.log(Currency: ${result.currency_code});
`

$3

`typescript
const result = await client.lookup('203.0.113.1');
console.log(Calling code: +${result.calling_code});
`

Authentication

Get your free API key from IPLocate.io, and pass it when creating the client:

`typescript
const client = new IPLocate('your-api-key');
`

Examples

$3

`typescript
import IPLocate from 'node-iplocate';

const client = new IPLocate('your-api-key');
const result = await client.lookup('203.0.113.1');

console.log(Country: ${result.country} (${result.country_code}));
if (result.latitude && result.longitude) {
console.log(Coordinates: ${result.latitude}, ${result.longitude});
}
`

$3

`typescript
const result = await client.lookup('192.0.2.1');

if (result.privacy.is_vpn) {
console.log('This IP is using a VPN');
}

if (result.privacy.is_proxy) {
console.log('This IP is using a proxy');
}

if (result.privacy.is_tor) {
console.log('This IP is using Tor');
}
`

$3

`typescript
const result = await client.lookup('8.8.8.8');

if (result.asn) {
console.log(ASN: ${result.asn.asn});
console.log(ISP: ${result.asn.name});
console.log(Network: ${result.asn.route});
}
`

$3

`typescript
import IPLocate from 'node-iplocate';

// Custom timeout and HTTP options
const client = new IPLocate('your-api-key', {
timeout: 60000, // 60 seconds
baseUrl: 'https://custom-endpoint.com/api', // For enterprise customers
httpClientOptions: {
headers: {
'Custom-Header': 'value'
}
}
});
`

Response structure

The LookupResponse interface contains all available data:

`typescript
interface LookupResponse {
ip: string;
country?: string;
country_code?: string;
is_eu: boolean;
city?: string;
continent?: string;
latitude?: number;
longitude?: number;
time_zone?: string;
postal_code?: string;
subdivision?: string;
currency_code?: string;
calling_code?: string;
network?: string;
asn?: ASN;
privacy: Privacy;
company?: Company;
hosting?: Hosting;
abuse?: Abuse;
}
`

$3

All types are exported for use in your TypeScript projects:

`typescript
import IPLocate, {
LookupResponse,
ASN,
Privacy,
Company,
Hosting,
Abuse,
IPLocateOptions
} from 'node-iplocate';
`

Error handling

The library provides typed error classes for different scenarios:

`typescript
import IPLocate, {
InvalidIPError,
AuthenticationError,
NotFoundError,
RateLimitError,
APIError
} from 'node-iplocate';

const client = new IPLocate('your-api-key');

try {
const result = await client.lookup('8.8.8.8');
console.log(result);
} catch (error) {
if (error instanceof InvalidIPError) {
console.log('Invalid IP address format');
} else if (error instanceof AuthenticationError) {
console.log('Invalid API key');
} else if (error instanceof NotFoundError) {
console.log('IP address not found');
} else if (error instanceof RateLimitError) {
console.log('Rate limit exceeded');
} else if (error instanceof APIError) {
console.log(API error (${error.statusCode}): ${error.message});
} else {
console.log('Unknown error:', error);
}
}
`

Common API errors:

- InvalidIPError: Invalid IP address format (HTTP 400)
- AuthenticationError: Invalid API key (HTTP 403)
- NotFoundError: IP address not found (HTTP 404)
- RateLimitError: Rate limit exceeded (HTTP 429)
- APIError: Other API errors (HTTP 500, etc.)

API reference

For complete API documentation, visit iplocate.io/docs.

Development

$3

`bash
yarn install
`

$3

`bash
yarn test
`

$3

`bash
yarn test:coverage
`

$3

`bash
yarn build
`

$3

`bash
yarn type-check
`

$3

`bash
yarn lint
yarn lint:fix
``

License

This project is licensed under the MIT License - see the LICENSE file for details.

About IPLocate.io

Since 2017, IPLocate has set out to provide the most reliable and accurate IP address data.

We process 50TB+ of data to produce our comprehensive IP geolocation, IP to company, proxy and VPN detection, hosting detection, ASN, and WHOIS data sets. Our API handles over 15 billion requests a month for thousands of businesses and developers.

- Email: support@iplocate.io
- Website: iplocate.io
- Documentation: iplocate.io/docs
- Sign up for a free API Key: iplocate.io/signup