geolocate
Retrieve geolocation details for an IP address or domain by inputting the query into the tool. Simplify location-based insights for seamless integration.
Instructions
Get geolocation information for an IP address or domain
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | IP address or domain to lookup |
Implementation Reference
- src/tools/geo.ts:55-100 (handler)The main handler function for the 'geolocate' tool. It checks the cache first, enforces rate limiting, fetches geolocation data from ip-api.com if necessary, caches successful results, and returns a JSON-formatted response.
handler: async ({ query }: { query: string }) => { // Check cache first const cached = geoCache.get(query); if (cached) { return { content: [{ type: 'text', text: JSON.stringify({ data: cached, source: 'cache' }, null, 2) }] }; } // Check rate limit if (!rateLimiter.canMakeRequest()) { const timeToReset = rateLimiter.getTimeToReset(); throw new Error(`Rate limit exceeded. Please try again in ${Math.ceil(timeToReset / 1000)} seconds.`); } try { const { data, rateLimit } = await fetchGeoData(query); // Update rate limiter based on response headers rateLimiter.incrementRequests(); // Cache successful responses if (data.status === 'success') { geoCache.set(query, data); } return { content: [{ type: 'text', text: JSON.stringify({ data, rateLimit, source: 'api' }, null, 2) }] }; } catch (error) { throw new Error(`Geolocation failed: ${error instanceof Error ? error.message : 'Unknown error'}`); } } - src/tools/geo.ts:42-54 (schema)Tool metadata including name, description, and input schema definition for 'geolocate', specifying a required 'query' string parameter.
geolocate: { name: 'geolocate', description: 'Get geolocation information for an IP address or domain', inputSchema: { type: 'object', properties: { query: { type: 'string', description: 'IP address or domain to lookup' } }, required: ['query'] }, - src/index.ts:27-33 (registration)Registration of the 'geolocate' tool by spreading geoTools into the central allTools registry used for listing and dispatching tool calls.
const allTools: ToolKit = { ...encodingTools, ...geoTools, ...generatorTools, ...dateTimeTools, ...securityTools }; - src/tools/geo.ts:7-39 (helper)Helper function that constructs the API request to ip-api.com, fetches geolocation data, and extracts rate limit information from headers.
async function fetchGeoData(query: string): Promise<{ data: GeoLocation; rateLimit: RateLimitInfo }> { const fields = [ 'status', 'message', 'country', 'countryCode', 'region', 'regionName', 'city', 'zip', 'lat', 'lon', 'timezone', 'offset', 'isp', 'org', 'as', 'query' ].join(','); const url = `http://ip-api.com/json/${encodeURIComponent(query)}?fields=${fields}`; const response = await fetch(url); const data = await response.json() as GeoLocation; const remaining = Number(response.headers.get('X-Rl') ?? '0'); const ttl = Number(response.headers.get('X-Ttl') ?? '0'); return { data, rateLimit: { remaining, ttl } }; } - src/tools/geo.ts:4-5 (helper)Initialization of the geolocation-specific cache (5 minutes TTL) and rate limiter (45 req/min) used by the handler.
const geoCache = new Cache<GeoLocation>(5 * 60 * 1000); // 5 minute cache const rateLimiter = new RateLimiter(45, 60000); // 45 requests per minute