rockygeo

Minimal fetch-based TypeScript client for the RockyGeo IP Geolocation API.

Use cases

• Content localization — pick language, currency, or regional content from country_code / region.
• Compliance and access control — gate features or block traffic by country or region.
• Analytics and segmentation — enrich server logs, events, or sign-ups with geo dimensions.
• Timezone-aware UX — schedule emails, show local times, or pick date formats from tz.
• Fraud and abuse signals — compare claimed location vs. IP-derived country/city as a risk signal.
• Bulk enrichment — resolve many IPs in one round trip with the batch endpoint (imports, ETL, nightly jobs).

Install

yarn add rockygeo

Requires Node.js 18+ (global fetch).

Quick start

import { RockyGeoClient } from 'rockygeo';

const client = new RockyGeoClient({ apiKey: 'your-api-key' });

const geo = await client.lookup('8.8.8.8');
console.log(geo.country, geo.city);

const batch = await client.lookupBatch(['8.8.8.8', '1.1.1.1']);
console.log(batch.results['8.8.8.8'].country_code);

const health = await client.health();
console.log(health.dataVersion, health.lastSyncAt);

Anonymous requests work without an API key (lower rate limit).

Get an API key

Subscribe through one of these providers for higher rate limits:

RapidAPI — Rocky Geo

Use your RapidAPI subscription key with the x-rapidapi-key header:

const client = new RockyGeoClient({
  apiKey: process.env.RAPIDAPI_KEY,
  authHeader: 'x-rapidapi-key',
});

API.market — Rocky Geo

Use your API.market subscription key with the default x-api-market-key header:

const client = new RockyGeoClient({
  apiKey: process.env.APIMARKET_KEY,
  healthEndpoint: '/health',
  healthBaseUrl: 'https://prod.api.market/api/v1/rocky/geo',
});

Configuration

| Option | Default | Description | |--------|---------|-------------| | baseUrl | https://prod.api.market | API base URL | | apiKey | — | API key | | authHeader | x-api-market-key | Auth header name (x-api-market-key or x-rapidapi-key) |

API reference

lookup(ip: string): Promise<GeoRecord>

Look up a single IPv4 or IPv6 address.

• Returns geolocation data on success (found: true).
• Throws RockyGeoError with status: 404 and ip when no geo data exists.
• Throws on invalid IP (400), rate limit (429), or server error (500).

lookupBatch(ips: string[]): Promise<BatchResponse>

Look up up to 100 IPs in one request.

• Always returns a results map on success.
• Unknown or invalid IPs appear with found: false (never returns 404).
• Validates batch size locally (1–100) before sending.

health(): Promise<HealthResponse>

Returns service health, data version, last sync time, and uptime. No authentication required.

Error handling

import { RockyGeoClient, RockyGeoError } from 'rockygeo';

try {
  await client.lookup('10.0.0.1');
} catch (error) {
  if (error instanceof RockyGeoError) {
    console.error(error.message, error.status, error.ip);

    if (error.status === 429 && error.rateLimit?.retryAfter) {
      console.log(`Retry after ${error.rateLimit.retryAfter}s`);
    }
  }
}

For batch lookups, check found on each result instead of catching 404:

const { results } = await client.lookupBatch(['8.8.8.8', '10.0.0.1']);
if (!results['10.0.0.1'].found) {
  console.log('No geo data for 10.0.0.1');
}

Types

Exported types: GeoRecord, BatchResponse, HealthResponse, RockyGeoClientConfig, RockyGeoAuthHeader, RockyGeoRateLimit, RockyGeoErrorBody.

License

MIT

#geolocation #geoip #ip #rockygeo #typescript #nodejs #ip-geolocation #api-client