Official JavaScript SDK for the IPGeolocation IP Location API.
Look up IPv4, IPv6, and domains with /v3/ipgeo and /v3/ipgeo-bulk. Get geolocation, company, ASN, timezone, network, hostname, abuse, user-agent, and security data from one API. Includes ESM, CommonJS, and TypeScript declarations.
Works in Node.js 18+ and in other runtimes that already provide fetch.
- Installation
- Quick Start
- At a Glance
- Get Your API Key
- What You Can Get From One API Call
- Security and Risk Signals
- Supported Endpoints
- Authentication Modes
- Plan Features and Limits
- Client Configuration
- Available Methods
- Request Options
- Single Lookup Examples
- Raw JSON and XML
- Bulk Lookup Examples
- Response Metadata
- JSON Helpers
- Error Handling
- Troubleshooting
- FAQ
- Related Packages
- Links
npm install ip-geolocation-api-javascript-sdkimport{IpGeolocationClient}from"ip-geolocation-api-javascript-sdk";const{ IpGeolocationClient }=require("ip-geolocation-api-javascript-sdk");import{IpGeolocationClient}from"ip-geolocation-api-javascript-sdk";asyncfunctionmain(){constclient=newIpGeolocationClient({apiKey: process.env.IPGEO_API_KEY,});try{constresponse=awaitclient.lookupIpGeolocation({ip: "8.8.8.8",});console.log("IP:",response.data.ip);// "8.8.8.8"console.log("Country:",response.data.location?.countryName);// "United States"console.log("City:",response.data.location?.city);console.log("Timezone:",response.data.timeZone?.name);console.log("Credits charged:",response.metadata.creditsCharged);}finally{awaitclient.close();}}main().catch((error)=>{console.error(error);});You can pass plain objects to request methods. If you want validation before the request is sent, use LookupIpGeolocationRequest and BulkLookupIpGeolocationRequest.
| Item | Value |
|---|---|
| Package | ip-geolocation-api-javascript-sdk |
| API Type | IPGeolocation IP Location API |
| Supported Endpoints | /v3/ipgeo, /v3/ipgeo-bulk |
| Supported Inputs | IPv4, IPv6, domain |
| Main Data Returned | Geolocation, company, ASN, timezone, network, security, abuse, hostname, user-agent, currency |
| Authentication | API key, request-origin auth for /v3/ipgeo only |
| Response Formats | Structured JSON, raw JSON, raw XML |
| Bulk Limit | Up to 50,000 IPs or domains per request |
| Runtime | Node.js 18+ or any runtime with fetch |
To use most SDK features, create or access your IPGeolocation account and copy an API key from your dashboard.
- Sign up: https://app.ipgeolocation.io/signup
- Verify your email if prompted
- Sign in: https://app.ipgeolocation.io/login
- Open your dashboard: https://app.ipgeolocation.io/dashboard
- Copy an API key from the
API Keyssection - Pass it to
new IpGeolocationClient({ apiKey: "YOUR_API_KEY" })
For server-side code, keep the API key in an environment variable or secret manager. For browser-based single lookups on paid plans, use request-origin auth instead of exposing an API key in frontend code.
| Data Set | How To Request It | Common Use Cases |
|---|---|---|
| IP geolocation | Default response | IP lookup, localization, geo targeting |
| Company and ASN | Default response | ISP lookup, ownership enrichment, network analysis |
| Timezone | Default response | Local time lookup, scheduling, regional reporting |
| Network and currency | Default response | Routing context, analytics, pricing flows |
| Security and risk signals | include: ["security"] | VPN detection, proxy detection, fraud prevention, threat analysis |
| Abuse contact data | include: ["abuse"] | Incident response, abuse handling, reporting |
| Hostname data | include: ["hostname"], ["liveHostname"], ["hostnameFallbackLive"] | Reverse DNS lookup, infrastructure enrichment, hosting checks |
| User-agent data | include: ["user_agent"] with userAgent or a User-Agent header | Browser detection, device detection, traffic analysis |
| Geo accuracy and DMA data | include: ["geo_accuracy"], ["dma_code"] | Local targeting, media market mapping, proximity analysis |
Request include: ["security"] when you need the security object in the response.
| Use Case | SDK Fields |
|---|---|
| VPN detection | security.isVpn, security.vpnProviderNames, security.vpnConfidenceScore, security.vpnLastSeen |
| Proxy detection | security.isProxy, security.proxyProviderNames, security.proxyConfidenceScore, security.proxyLastSeen |
| Residential proxy detection | security.isResidentialProxy |
| Tor detection | security.isTor |
| Anonymous IP detection | security.isAnonymous |
| Threat score and risk scoring | security.threatScore |
| Bot, spam, and attacker signals | security.isBot, security.isSpam, security.isKnownAttacker |
| Relay detection | security.isRelay, security.relayProviderName |
| Cloud, hosting, or data center IP detection | security.isCloudProvider, security.cloudProviderName |
Provider names, confidence scores, and last-seen dates appear when the API has that data.
| Endpoint | HTTP Method | SDK Methods | Primary Use Case |
|---|---|---|---|
/v3/ipgeo | GET | lookupIpGeolocation(...), lookupIpGeolocationRaw(...) | Single IPv4, IPv6, or domain lookup |
/v3/ipgeo-bulk | POST | bulkLookupIpGeolocation(...), bulkLookupIpGeolocationRaw(...) | Bulk lookup for up to 50,000 IPs or domains |
These two endpoints can return geolocation, company, ASN, timezone, network, currency, hostname, abuse, user-agent, and security data depending on your request and plan.
| Mode | SDK Setup | Typical Use |
|---|---|---|
| API key query param | new IpGeolocationClient({ apiKey: "YOUR_API_KEY" }) | Server-side API calls, jobs, bulk lookups |
| Request-origin auth | new IpGeolocationClient({ requestOrigin: "https://app.example.com" }) | Browser-based single lookups on paid plans |
Important
Request-origin auth does not work with /v3/ipgeo-bulk. Bulk lookup always requires apiKey.
Note
If you set both apiKey and requestOrigin, single lookup still uses the API key. The API key is sent as the apiKey query parameter, so avoid logging full request URLs.
Feature availability depends on your plan and request parameters.
| Capability | Free Plan | Paid Plan |
|---|---|---|
| IPv4 and IPv6 single lookup | Supported | Supported |
| Domain lookup | Not supported | Supported |
Bulk endpoint /v3/ipgeo-bulk | Not supported | Supported, but always requires an API key |
include: ["*"] | Accepted, returns the default response only | Accepted, returns all available modules |
include: ["security"], ["abuse"], ["hostname"], ["liveHostname"], ["hostnameFallbackLive"], ["geo_accuracy"], ["dma_code"], ["user_agent"] | Not supported | Supported |
Non-English lang | Not supported | Supported |
fields and excludes | Supported | Supported |
| Request-origin auth | Not supported | Supported for /v3/ipgeo only |
Paid plans still need include for optional modules. fields and excludes only trim the response. They do not turn modules on or unlock paid data.
| Option | Type | Default | Notes |
|---|---|---|---|
apiKey | string | unset | Required for bulk lookup. Optional for single lookup if requestOrigin is set. |
requestOrigin | string | unset | Must be an absolute http or https origin. No path, query string, fragment, or userinfo. |
baseUrl | string | https://api.ipgeolocation.io | Override the API base URL. Must be an absolute http or https URL. |
connectTimeoutMs | number | 10000 | Time to wait for response headers. Must be a positive integer. |
readTimeoutMs | number | 30000 | Time to wait while reading the response body. Must be a positive integer. |
You can also pass a custom HttpTransport as the second constructor argument.
| Method | Returns | Notes |
|---|---|---|
lookupIpGeolocation(request) | Promise<ApiResponse<IpGeolocationResponse>> | Single lookup. Typed JSON response. |
lookupIpGeolocationRaw(request) | Promise<ApiResponse<string>> | Single lookup. Raw JSON or XML string. |
bulkLookupIpGeolocation(request) | Promise<ApiResponse<readonly BulkLookupResult[]>> | Bulk lookup. Typed JSON response. |
bulkLookupIpGeolocationRaw(request) | Promise<ApiResponse<string>> | Bulk lookup. Raw JSON or XML string. |
close() | Promise<void> | Closes the client. Do not reuse the client after this. |
Note
Typed methods support JSON only. Use the raw methods when you need XML output.
| Option | Applies To | Notes |
|---|---|---|
ip | Single lookup | IPv4, IPv6, or domain. Omit it for caller IP lookup. Domain lookup requires a paid plan. |
ips | Bulk lookup | Iterable of 1 to 50,000 IPs or domains. |
lang | Single and bulk | One of en, de, ru, ja, fr, cn, es, cs, it, ko, fa, pt. |
include | Single and bulk | Iterable of module names such as security, abuse, user_agent, hostname, liveHostname, hostnameFallbackLive, geo_accuracy, dma_code, or *. |
fields | Single and bulk | Iterable of field paths to keep, for example ["location.country_name", "security.threat_score"]. |
excludes | Single and bulk | Iterable of field paths to remove from the response. |
userAgent | Single and bulk | Overrides the outbound User-Agent header. If you also pass a User-Agent header in headers, userAgent wins. |
headers | Single and bulk | Extra request headers. Use a plain object, Headers, Map, or iterable of [name, value] pairs. |
output | Single and bulk | "json" or "xml". Typed methods require JSON. |
The examples below assume you already have a configured client and are running inside an async function or an ESM module with top-level await:
import{IpGeolocationClient}from"ip-geolocation-api-javascript-sdk";constclient=newIpGeolocationClient({apiKey: process.env.IPGEO_API_KEY,});Omit ip to look up the public IP of the machine making the request.
constresponse=awaitclient.lookupIpGeolocation({});console.log(response.data.ip);Domain lookup is a paid-plan feature.
constresponse=awaitclient.lookupIpGeolocation({ip: "ipgeolocation.io",});console.log(response.data.ip);console.log(response.data.domain);// "ipgeolocation.io"console.log(response.data.location?.countryName);constresponse=awaitclient.lookupIpGeolocation({ip: "9.9.9.9",include: ["security","abuse"],});console.log(response.data.security?.threatScore);console.log(response.data.security?.isVpn);console.log(response.data.abuse?.emails?.[0]);constresponse=awaitclient.lookupIpGeolocation({ip: "ipgeolocation.io",include: ["hostname","liveHostname","hostnameFallbackLive"],});console.log(response.data.hostname);To parse a visitor user-agent string, request user_agent and pass the visitor string in userAgent.
constresponse=awaitclient.lookupIpGeolocation({ip: "8.8.8.8",include: ["user_agent"],userAgent:
"Mozilla/5.0 (Macintosh; Intel Mac OS X 10_11_2) "+"AppleWebKit/601.3.9 (KHTML, like Gecko) Version/9.0.2 Safari/601.3.9",});console.log(response.data.userAgent?.name);console.log(response.data.userAgent?.operatingSystem?.name);console.log(response.data.userAgent?.device?.type);Use fields to keep only the data you need, or excludes to remove fields from the response.
constresponse=awaitclient.lookupIpGeolocation({ip: "8.8.8.8",include: ["security"],fields: ["location.country_name","security.threat_score","security.is_vpn"],excludes: ["currency"],});console.log(response.data.location?.countryName);console.log(response.data.security?.threatScore);console.log(response.data.security?.isVpn);If you want request validation before sending the call, create the request explicitly.
import{IpGeolocationClient,LookupIpGeolocationRequest,}from"ip-geolocation-api-javascript-sdk";constclient=newIpGeolocationClient({apiKey: process.env.IPGEO_API_KEY,});constrequest=newLookupIpGeolocationRequest({ip: "8.8.8.8",include: ["security"],});constresponse=awaitclient.lookupIpGeolocation(request);console.log(response.data.security?.isProxy);Use this only for paid-plan single lookups from an allowlisted origin.
constbrowserClient=newIpGeolocationClient({requestOrigin: "https://app.example.com",});constresponse=awaitbrowserClient.lookupIpGeolocation({ip: "8.8.8.8",});console.log(response.data.ip);awaitbrowserClient.close();Use raw methods when you want the original response body as a string.
import{IpGeolocationClient,ResponseFormat,}from"ip-geolocation-api-javascript-sdk";constclient=newIpGeolocationClient({apiKey: process.env.IPGEO_API_KEY,});constrawJson=awaitclient.lookupIpGeolocationRaw({ip: "8.8.8.8",});console.log(rawJson.data);constrawXml=awaitclient.lookupIpGeolocationRaw({ip: "8.8.8.8",output: ResponseFormat.XML,});console.log(rawXml.data);Bulk lookup is a paid-plan feature and always requires apiKey.
constresponse=awaitclient.bulkLookupIpGeolocation({ips: ["8.8.8.8","1.1.1.1"],});for(constresultofresponse.data){if(result.success){console.log(result.data.ip,result.data.location?.countryName);// "8.8.8.8", "United States"}}Each bulk result is either a success with data or an error with error.message.
constresponse=awaitclient.bulkLookupIpGeolocation({ips: ["8.8.8.8","invalid-ip","1.1.1.1"],include: ["security"],});for(constresultofresponse.data){if(result.success){console.log(result.data.ip,result.data.security?.threatScore);continue;}console.error(result.error.message);}Every SDK call returns an object with data and metadata.
metadata is an ApiResponseMetadata instance with:
| Field | Meaning |
|---|---|
statusCode | HTTP status code returned by the API |
durationMs | End-to-end request time measured by the SDK |
creditsCharged | Credits charged for the request, when returned by the API |
successfulRecords | Number of successful records for bulk lookups, when returned by the API |
rawHeaders | Raw response headers as a multi-map |
It also provides:
metadata.headerValues(name)metadata.firstHeaderValue(name)
Example:
constresponse=awaitclient.lookupIpGeolocation({ip: "8.8.8.8",});console.log(response.metadata.statusCode);console.log(response.metadata.durationMs);console.log(response.metadata.firstHeaderValue("x-ratelimit-remaining"));Use toJson() or toPrettyJson() when you want a stable JSON view of SDK objects.
import{toPrettyJson}from"ip-geolocation-api-javascript-sdk";constresponse=awaitclient.lookupIpGeolocation({ip: "8.8.8.8",});console.log(toPrettyJson(response.data));All SDK errors extend IpGeolocationError.
Runtime and validation errors:
ValidationErrorSerializationErrorTransportErrorRequestTimeoutError
API errors:
ApiErrorBadRequestErrorUnauthorizedErrorNotFoundErrorMethodNotAllowedErrorPayloadTooLargeErrorUnsupportedMediaTypeErrorLockedErrorRateLimitErrorClientClosedRequestErrorServerError
ApiError and its subclasses expose:
statusCodeapiMessage
Example:
import{IpGeolocationClient,RateLimitError,UnauthorizedError,}from"ip-geolocation-api-javascript-sdk";constclient=newIpGeolocationClient({apiKey: process.env.IPGEO_API_KEY,});try{constresponse=awaitclient.lookupIpGeolocation({ip: "8.8.8.8",});console.log(response.data.location?.countryName);}catch(error){if(errorinstanceofUnauthorizedError){console.error(error.apiMessage);}elseif(errorinstanceofRateLimitError){console.error("Rate limit reached");}else{throwerror;}}finally{awaitclient.close();}Set either apiKey or requestOrigin when creating the client.
Bulk lookup always requires apiKey, even if requestOrigin is set.
Those features require a paid plan. Free plans only support the base single-lookup response.
Use lookupIpGeolocationRaw(...) or bulkLookupIpGeolocationRaw(...) with output: "xml".
Create a new client after calling close(). Closed clients cannot be reused.
Increase connectTimeoutMs or readTimeoutMs if your environment needs longer network time.
Can I use this SDK in the browser?
Yes, if your runtime provides `fetch`. Do not expose `apiKey` in frontend code. For browser single lookups on paid plans, use `requestOrigin`.Does the SDK retry failed requests?
No. Timeouts, rate limits, and server errors are raised directly. Add your own retry policy outside the SDK if you need one.Can I pass custom headers?
Yes. Use `headers` with a plain object, `Headers`, `Map`, or an iterable of `[name, value]` pairs.Does `userAgent` do the same thing as `headers["User-Agent"]`?
Almost. Both affect the outbound `User-Agent` header, but `userAgent` takes precedence when both are set.Can I use request-origin auth with bulk lookup?
No. Bulk lookup always requires `apiKey`.Do typed methods support XML?
No. Typed methods require JSON. Use raw methods if you need XML.- TypeScript runtime SDK:
ip-geolocation-api-sdk-typescript - TypeScript types-only package:
ip-geolocation-api-typescript-types