feat: ✨ add LocationIQ geocoder, tests, example, and docs

Author: hsborges

AGENTS.md

@@ -14,7 +14,7 @@ This document provides comprehensive guidelines for AI coding agents working in
 - **Testing:** Vitest 4.x with @vitest/coverage-v8
 - **Project Type:** Monorepo with workspaces (packages/core, packages/cli)
 
-**Purpose:** Geocoding service that resolves GitHub user location strings to standardized addresses using OpenStreetMap/Nominatim API.
+**Purpose:** Geocoding service that resolves GitHub user location strings to standardized addresses using OpenStreetMap/Nominatim and additional providers (e.g., LocationIQ).
 
 ## Project Structure
 

README.md

@@ -6,6 +6,8 @@ Esse script é necessário uma vez que as localizações informadas são livres,
 
 Para isso usamos do [Nominatim](https://nominatim.openstreetmap.org/), uma search engine do OpenStreetMap, para resolver a localização provida em um local padronizado (país, estado, cidade, etc.).
 
+Também suportamos provedores comerciais como LocationIQ. O provedor LocationIQ exige uma chave de API — exporte a variável de ambiente LOCATIONIQ_KEY ou passe o apiKey ao construir o serviço.
+
 ## Instalação
 
 ```bash

packages/core/README.md

@@ -64,6 +64,31 @@ OpenStreetMap(options: { concurrency: number; minConfidence: number })
 - `options.concurrency`: The number of concurrent requests allowed.
 - `options.minConfidence`: The minimum confidence level required for a result.
 
+### LocationIQ
+
+The LocationIQ class provides geocoding functionality using the LocationIQ API. It requires an API key.
+
+```typescript
+LocationIQ(options: { apiKey: string; baseUrl?: string; concurrency?: number; minConfidence?: number })
+```
+
+- `options.apiKey`: Required. Your LocationIQ API key (can also be provided via env LOCATIONIQ_KEY).
+- `options.baseUrl`: Optional. Custom LocationIQ base URL (default: https://us1.locationiq.com/v1).
+- `options.concurrency`: Optional. Number of concurrent requests.
+- `options.minConfidence`: Optional. Minimum confidence to accept a result.
+
+Example:
+
+```typescript
+import { LocationIQ, Cache } from '../src/index.js';
+
+const locationiq = new LocationIQ({ apiKey: process.env.LOCATIONIQ_KEY!, concurrency: 1, minConfidence: 0.5 });
+const service = new Cache(locationiq, { dirname: '/tmp/addresses.json', size: 1000, ttl: 3600 });
+
+const res = await service.search('Seattle');
+console.log(res);
+```
+
 ### Cache
 
 The Cache class provides a caching mechanism for the geocoding service.

packages/core/examples/locationiq.ts

@@ -0,0 +1,28 @@
+import consola from 'consola';
+import prettyformat from 'pretty-format';
+import { LocationIQ } from '../src/index.js';
+
+(async function main() {
+  // Ensure you set LOCATIONIQ_KEY in your environment
+  const apiKey = process.env.LOCATIONIQ_KEY;
+  if (!apiKey) {
+    throw new Error('LOCATIONIQ_KEY environment variable is required for this example');
+  }
+
+  // Create a new instance of the LocationIQ service
+  const locationiq = new LocationIQ({
+    apiKey,
+    concurrency: 1,
+    minConfidence: 0.5
+  });
+
+  // Example searches
+  let response = await locationiq.search('Seattle, WA');
+  consola.info(prettyformat(response, { min: true }));
+
+  response = await locationiq.search('Earth planet');
+  consola.info(prettyformat(response, { min: true }));
+
+  response = await locationiq.search('Brazil');
+  consola.info(prettyformat(response, { min: true }));
+})();

packages/core/src/entities/Address.ts

@@ -14,7 +14,7 @@ export const AddressSchema = z.preprocess(
     country_code: z.string().toUpperCase().optional().describe('The country code'),
     state: z.string().optional().describe('The state name'),
     city: z.string().optional().describe('The city name'),
-    provider: z.enum(['openstreetmap', 'photon']).describe('The geocoding provider')
+    provider: z.enum(['openstreetmap', 'photon', 'locationiq']).describe('The geocoding provider')
   })
 );
 

packages/core/src/geocoder/LocationIQ.ts

@@ -0,0 +1,93 @@
+import Debug from 'debug';
+import { type Address, AddressSchema } from '../entities/Address.js';
+import fetch from '../helpers/fetch.js';
+import { Throttler } from './decorators/Throttler.js';
+import { Geocoder } from './Geocoder.js';
+
+const debug = Debug('geocoder:locationiq');
+
+type LocationIQSearchResult = {
+  display_name: string;
+  class?: string;
+  type?: string;
+  importance?: number;
+  rank_search?: number;
+  address?: Record<string, any>;
+};
+
+export type BaseLocationIQOptions = {
+  apiKey: string;
+  baseUrl?: string;
+  minConfidence?: number;
+};
+
+class BaseLocationIQ implements Geocoder {
+  constructor(private options: BaseLocationIQOptions) {
+    debug('initializing with options (hidden apiKey): %O', {
+      baseUrl: options.baseUrl,
+      minConfidence: options.minConfidence
+    });
+  }
+
+  async search(q: string, options?: { signal?: AbortSignal }): Promise<Address | null> {
+    debug('searching for: %s', q);
+
+    const base = this.options.baseUrl ?? 'https://us1.locationiq.com/v1';
+    const params = new URLSearchParams({
+      key: this.options.apiKey,
+      q,
+      format: 'json',
+      addressdetails: '1',
+      limit: '5'
+    });
+
+    const url = `${base}/search.php?${params.toString()}`;
+
+    const raw = await fetch<LocationIQSearchResult[]>(url, { signal: options?.signal });
+    // Support both Response-like objects (with .json()) and direct JSON returned by mocks
+    const response =
+      typeof (raw as any)?.json === 'function' ? await (raw as any).json() : (raw as any);
+
+    if (!Array.isArray(response) || response.length === 0) {
+      debug('no results from locationiq for: %s', q);
+      return null;
+    }
+
+    const candidate = response[0];
+    if (!candidate) return null;
+
+    const addr = candidate.address ?? {};
+    const confidence = Number(candidate.importance ?? candidate.rank_search ?? 0);
+
+    if (this.options.minConfidence && confidence < this.options.minConfidence) {
+      debug('confidence below threshold: %s < %s', confidence, this.options.minConfidence);
+      return null;
+    }
+
+    const result = AddressSchema.parse({
+      provider: 'locationiq',
+      source: q,
+      name: [addr.country, addr.state ?? addr.county, addr.city ?? addr.town ?? addr.village]
+        .filter(Boolean)
+        .join(', '),
+      type: candidate.type ?? candidate.class,
+      confidence,
+      country: addr.country,
+      country_code: addr.country_code?.toUpperCase?.(),
+      state: addr.state ?? addr.county,
+      city: addr.city ?? addr.town ?? addr.village
+    });
+
+    debug('found address: %s (confidence: %s)', result.name, result.confidence);
+    return result;
+  }
+}
+
+export type LocationIQOptions = { concurrency?: number } & BaseLocationIQOptions;
+
+export class LocationIQ extends Throttler implements Geocoder {
+  constructor(options: LocationIQOptions) {
+    const { concurrency, ...opts } = options;
+    super(new BaseLocationIQ(opts), { concurrency, intervalCap: 1000 });
+  }
+}

packages/core/src/geocoder/decorators/README.md

@@ -47,6 +47,11 @@ const geocoder = new Throttler(
   new OpenStreetMap(config),
   { concurrency: 1, intervalCap: 1000 }
 );
+
+// Throttler can be used with LocationIQ as well
+import { LocationIQ } from '../../LocationIQ.js';
+const li = new LocationIQ({ apiKey: process.env.LOCATIONIQ_KEY, concurrency: 1 });
+const throttled = new Throttler(li, { concurrency: 1, intervalCap: 1000 });
 ```
 
 ### Fallback

packages/core/src/geocoder/index.ts

@@ -4,5 +4,6 @@ export * from './decorators/LoadBalancer.js';
 export * from './decorators/Throttler.js';
 
 export * from './Geocoder.js';
+export * from './LocationIQ.js';
 export * from './OpenStreetMap.js';
 export * from './Photon.js';