csv2geo-sdk 1.0.1 → 1.2.0

package/README.md

@@ -51,7 +51,7 @@ if (result) {
 const { Client } = require('csv2geo-sdk');
 
 const client = new Client('your_api_key', {
-  baseUrl: 'https://api.csv2geo.com/v1',  // optional
+  baseUrl: 'https://csv2geo.com/api/v1',  // optional
   timeout: 30000,  // optional, milliseconds
   autoRetry: true,  // optional, retry on rate limit
 });
@@ -203,6 +203,11 @@ Sign up at [csv2geo.com](https://csv2geo.com) to get your API key.
 - [API Documentation](https://acenji.github.io/csv2geo-api/docs/)
 - [OpenAPI Specification](https://github.com/acenji/csv2geo-api/blob/main/openapi.yaml)
 
+## Community & Support
+
+- **Questions & feature requests:** [GitHub Discussions](https://github.com/acenji/csv2geo-api/discussions)
+- **Bug reports:** [GitHub Issues](https://github.com/acenji/csv2geo-api/issues)
+
 ## License
 
 MIT License - see [LICENSE](https://github.com/acenji/csv2geo-api/blob/main/LICENSE) for details.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "csv2geo-sdk",
-  "version": "1.0.1",
-  "description": "Node.js SDK for CSV2GEO Geocoding API — 461M+ addresses, 200+ countries, 18 endpoints. Forward, reverse, batch, places, divisions, autocomplete. 1,000 free requests/day.",
+  "version": "1.2.0",
+  "description": "Node.js SDK for CSV2GEO Geocoding API — 461M+ addresses, 39 countries, 42+ endpoints. Forward, reverse, batch, places, divisions (incl. postcode → boundary), IP geolocation with county overlay, coverage, autocomplete. 3,000 free requests/day.",
   "main": "src/index.js",
   "types": "src/index.d.ts",
   "files": [

package/src/index.d.ts

@@ -3,7 +3,7 @@
  */
 
 export interface ClientOptions {
-  /** API base URL (default: https://api.csv2geo.com/v1) */
+  /** API base URL (default: https://csv2geo.com/api/v1) */
   baseUrl?: string;
   /** Request timeout in milliseconds (default: 30000) */
   timeout?: number;
@@ -105,6 +105,44 @@ export class Client {
    * @returns Array of responses
    */
   reverseBatch(coordinates: Coordinate[]): Promise<GeocodeResponse[]>;
+
+  /**
+   * IP geolocation. Returns country/region/city/postcode/location/timezone/ISP,
+   * plus county + locality + confidence for residential IPs (Sprint 2.7).
+   * @param ip IPv4 or IPv6 string
+   */
+  ip(ip: string): Promise<IPGeoResponse>;
+
+  /**
+   * Like {@link ip}, but uses the requester's IP.
+   */
+  ipMe(): Promise<IPGeoResponse>;
+
+  /**
+   * Batch IP lookup. Up to 1000 IPs per call.
+   */
+  ipBatch(ips: string[]): Promise<{ results: IPGeoResponse[] }>;
+}
+
+export interface IPGeoResponse {
+  ip: string;
+  country?: { code: string; name?: string; wikidata?: string };
+  region?: { code?: string; name?: string };
+  city?: { name: string };
+  postcode?: string;
+  location?: {
+    latitude: number;
+    longitude: number;
+    accuracy_radius_km: number;
+  };
+  timezone?: string;
+  isp?: { asn?: number; name?: string };
+  county?: { name: string; subtype?: string; wikidata?: string };
+  locality?: { name: string; subtype?: string; wikidata?: string };
+  confidence?: 'high' | 'medium' | 'low';
+  accuracy_disclaimer?: string;
+  source: string;
+  db_build_at?: string;
 }
 
 export class CSV2GEOError extends Error {

package/src/index.js

@@ -20,7 +20,7 @@ const {
   APIError,
 } = require('./errors');
 
-const DEFAULT_BASE_URL = 'https://api.csv2geo.com/v1';
+const DEFAULT_BASE_URL = 'https://csv2geo.com/api/v1';
 const DEFAULT_TIMEOUT = 30000;
 const MAX_RETRIES = 3;
 
@@ -75,7 +75,7 @@ class Client {
         headers: {
           'Authorization': `Bearer ${this.apiKey}`,
           'Content-Type': 'application/json',
-          'User-Agent': 'csv2geo-node/1.0.0',
+          'User-Agent': 'csv2geo-node/1.2.0',
         },
         signal: controller.signal,
       };
@@ -260,6 +260,286 @@ class Client {
     }));
   }
 
+  // ─────────────────────────────────────────────────────────
+  // Address Tools
+  // ─────────────────────────────────────────────────────────
+
+  /** Validate an address. GET /validate */
+  async validate(address, options = {}) {
+    const params = { q: address };
+    if (options.country) params.country = options.country;
+    return this._request('GET', '/validate', params);
+  }
+
+  /** Validate up to 10,000 addresses. POST /validate */
+  async validateBatch(addresses) {
+    if (addresses.length > 10000) throw new InvalidRequestError('Max 10,000 per batch');
+    return this._request('POST', '/validate', {}, { addresses });
+  }
+
+  /** Address autocomplete suggestions. GET /autocomplete */
+  async autocomplete(query, options = {}) {
+    const params = { q: query };
+    if (options.country) params.country = options.country;
+    if (options.limit)   params.limit   = options.limit;
+    return this._request('GET', '/autocomplete', params);
+  }
+
+  /** Parse a free-form address into components. GET /parse */
+  async parse(address) {
+    return this._request('GET', '/parse', { q: address });
+  }
+
+  /** Parse up to 10,000 addresses. POST /parse */
+  async parseBatch(addresses) {
+    if (addresses.length > 10000) throw new InvalidRequestError('Max 10,000 per batch');
+    return this._request('POST', '/parse', {}, { addresses });
+  }
+
+  /** Standardize an address. GET /standardize */
+  async standardize(address) {
+    return this._request('GET', '/standardize', { q: address });
+  }
+
+  /** Score similarity between two addresses. GET /addresses/compare */
+  async compareAddresses(address1, address2) {
+    return this._request('GET', '/addresses/compare', { a: address1, b: address2 });
+  }
+
+  // ─────────────────────────────────────────────────────────
+  // Address inspection
+  // ─────────────────────────────────────────────────────────
+
+  /** Find addresses within radius of a coordinate. GET /addresses/nearby */
+  async addressesNearby(lat, lng, options = {}) {
+    const params = { lat, lng, radius: options.radius || 200 };
+    if (options.limit) params.limit = options.limit;
+    return this._request('GET', '/addresses/nearby', params);
+  }
+
+  /** Get all addresses on a street. GET /addresses/street */
+  async addressesStreet(country, city, street) {
+    return this._request('GET', '/addresses/street', { country, city, street });
+  }
+
+  /** Address counts. GET /addresses/stats */
+  async addressesStats(country) {
+    const params = {};
+    if (country) params.country = country;
+    return this._request('GET', '/addresses/stats', params);
+  }
+
+  /** Random sample of addresses. GET /addresses/random */
+  async addressesRandom(options = {}) {
+    const params = { limit: options.limit || 1 };
+    if (options.country) params.country = options.country;
+    return this._request('GET', '/addresses/random', params);
+  }
+
+  /** Interpolate a coordinate from address-range data. GET /addresses/interpolate */
+  async addressesInterpolate(country, city, street, houseNumber) {
+    return this._request('GET', '/addresses/interpolate',
+      { country, city, street, house_number: houseNumber });
+  }
+
+  /** Find the intersection of two streets. GET /addresses/crossstreet */
+  async addressesCrossstreet(country, city, streetA, streetB) {
+    return this._request('GET', '/addresses/crossstreet',
+      { country, city, street_a: streetA, street_b: streetB });
+  }
+
+  // ─────────────────────────────────────────────────────────
+  // Places
+  // ─────────────────────────────────────────────────────────
+
+  /** Search places (POIs). GET /places */
+  async places(options = {}) {
+    const params = {};
+    if (options.q || options.query) params.q = options.q || options.query;
+    if (options.country)            params.country = options.country;
+    if (options.category)           params.category = options.category;
+    if (options.limit)              params.limit = options.limit;
+    return this._request('GET', '/places', params);
+  }
+
+  /** Places within radius of a coordinate. GET /places/nearby */
+  async placesNearby(lat, lng, options = {}) {
+    const params = { lat, lng, radius: options.radius || 200 };
+    if (options.category) params.category = options.category;
+    if (options.limit)    params.limit = options.limit;
+    return this._request('GET', '/places/nearby', params);
+  }
+
+  /** List all place categories. GET /places/categories */
+  async placesCategories() {
+    return this._request('GET', '/places/categories');
+  }
+
+  /** Random places. GET /places/random */
+  async placesRandom(options = {}) {
+    const params = { limit: options.limit || 1 };
+    if (options.country)  params.country = options.country;
+    if (options.category) params.category = options.category;
+    return this._request('GET', '/places/random', params);
+  }
+
+  /** Places counts. GET /places/stats */
+  async placesStats(country) {
+    const params = {};
+    if (country) params.country = country;
+    return this._request('GET', '/places/stats', params);
+  }
+
+  /** List brand-tagged places. GET /places/brands */
+  async placesBrands(country) {
+    const params = {};
+    if (country) params.country = country;
+    return this._request('GET', '/places/brands', params);
+  }
+
+  /** All locations of a brand/chain. GET /places/chain */
+  async placesChain(brand, country) {
+    const params = { brand };
+    if (country) params.country = country;
+    return this._request('GET', '/places/chain', params);
+  }
+
+  /** Count places matching filter. GET /places/count */
+  async placesCount(options = {}) {
+    const params = {};
+    if (options.country)  params.country = options.country;
+    if (options.category) params.category = options.category;
+    return this._request('GET', '/places/count', params);
+  }
+
+  /** Places similar to a given one. GET /places/similar */
+  async placesSimilar(placeId, options = {}) {
+    const params = { id: placeId };
+    if (options.limit) params.limit = options.limit;
+    return this._request('GET', '/places/similar', params);
+  }
+
+  /** Batch nearby-places lookup. POST /places/batch */
+  async placesBatch(coordinates, options = {}) {
+    if (coordinates.length > 10000) throw new InvalidRequestError('Max 10,000 per batch');
+    const body = { coordinates, radius: options.radius || 200 };
+    if (options.category) body.category = options.category;
+    return this._request('POST', '/places/batch', {}, body);
+  }
+
+  /** Single place by id. GET /places/{id} */
+  async placeById(placeId) {
+    return this._request('GET', `/places/${encodeURIComponent(placeId)}`);
+  }
+
+  // ─────────────────────────────────────────────────────────
+  // Divisions (Sprint 1 — postcode boundary)
+  // ─────────────────────────────────────────────────────────
+
+  /** Search administrative divisions. GET /divisions */
+  async divisionsSearch(options = {}) {
+    const params = {};
+    if (options.q || options.query) params.q = options.q || options.query;
+    if (options.country)            params.country = options.country;
+    if (options.subtype)            params.subtype = options.subtype;
+    if (options.limit)              params.limit = options.limit;
+    return this._request('GET', '/divisions', params);
+  }
+
+  /** Point-in-polygon: divisions containing a point. GET /divisions/contains */
+  async divisionsContains(lat, lng) {
+    return this._request('GET', '/divisions/contains', { lat, lng });
+  }
+
+  /**
+   * Postcode → boundary (bbox + optional polygon + population + wikidata).
+   * GET /divisions/by-postcode
+   *
+   * @param {string} code - Postcode (e.g. "90210", "SW1A 1AA")
+   * @param {string} country - ISO 3166-1 alpha-2
+   * @param {Object} [options]
+   * @param {string} [options.include] - "geometry" to include polygon
+   * @param {string} [options.precision] - "simplified" (default) or "full"
+   *
+   * @example
+   *   const r = await client.divisionsByPostcode('90210', 'US', { include: 'geometry' });
+   *   console.log(r.result.population, r.result.bbox);
+   */
+  async divisionsByPostcode(code, country, options = {}) {
+    const params = { code, country };
+    if (options.include)   params.include = options.include;
+    if (options.precision) params.precision = options.precision;
+    return this._request('GET', '/divisions/by-postcode', params);
+  }
+
+  /** List available division subtypes. GET /divisions/subtypes */
+  async divisionsSubtypes() {
+    return this._request('GET', '/divisions/subtypes');
+  }
+
+  /** List countries with division coverage. GET /divisions/countries */
+  async divisionsCountries() {
+    return this._request('GET', '/divisions/countries');
+  }
+
+  /** Division counts. GET /divisions/stats */
+  async divisionsStats(country) {
+    const params = {};
+    if (country) params.country = country;
+    return this._request('GET', '/divisions/stats', params);
+  }
+
+  /** Random divisions. GET /divisions/random */
+  async divisionsRandom(options = {}) {
+    const params = { limit: options.limit || 1 };
+    if (options.country) params.country = options.country;
+    if (options.subtype) params.subtype = options.subtype;
+    return this._request('GET', '/divisions/random', params);
+  }
+
+  /** Full parent/child chain for a division. GET /divisions/hierarchy/{id} */
+  async divisionHierarchy(divisionId) {
+    return this._request('GET', `/divisions/hierarchy/${encodeURIComponent(divisionId)}`);
+  }
+
+  /** Single division by id. GET /divisions/{id} */
+  async divisionById(divisionId) {
+    return this._request('GET', `/divisions/${encodeURIComponent(divisionId)}`);
+  }
+
+  // ─────────────────────────────────────────────────────────
+  // Coverage
+  // ─────────────────────────────────────────────────────────
+
+  /** Live tier-by-country coverage matrix. GET /coverage */
+  async coverage() {
+    return this._request('GET', '/coverage');
+  }
+
+  /** Aggregate coverage totals. GET /coverage-stats */
+  async coverageStats() {
+    return this._request('GET', '/coverage-stats');
+  }
+
+  // ─────────────────────────────────────────────────────────
+  // Utilities
+  // ─────────────────────────────────────────────────────────
+
+  /** Timezone at a coordinate. GET /timezone */
+  async timezone(lat, lng) {
+    return this._request('GET', '/timezone', { lat, lng });
+  }
+
+  /** Great-circle distance between two coordinates. GET /distance */
+  async distance(lat1, lng1, lat2, lng2) {
+    return this._request('GET', '/distance', { lat1, lng1, lat2, lng2 });
+  }
+
+  /** Service health check. GET /health */
+  async health() {
+    return this._request('GET', '/health');
+  }
+
   /**
    * Parse API result into GeocodeResult
    * @private
@@ -283,6 +563,56 @@ class Client {
       },
     };
   }
+
+  // ─────────────────────────────────────────────────────────
+  // IP geolocation (Sprint 2.7)
+  //
+  // MaxMind GeoLite2 .mmdb lookup with our county overlay.
+  // Bundled into every plan (including Free); no separate billing.
+  // ─────────────────────────────────────────────────────────
+
+  /**
+   * IP → geolocation. Returns country, region, city, postcode, location,
+   * timezone, ISP, and (for residential IPs) county + locality + confidence.
+   *
+   * @param {string} ip - IPv4 or IPv6 address (e.g. "8.8.8.8")
+   * @returns {Promise<Object>} canonical /v1/ip response shape
+   * @example
+   *   const r = await client.ip('8.8.8.8');
+   *   console.log(r.country.code, r.county?.name, r.confidence);
+   */
+  async ip(ip) {
+    if (!ip || typeof ip !== 'string') {
+      throw new InvalidRequestError('ip must be a non-empty string');
+    }
+    return this._request('GET', '/ip', { ip });
+  }
+
+  /**
+   * Like {@link ip}, but uses the requester's IP (the one Laravel sees).
+   * Useful from browser/server contexts where you want "where is the caller".
+   *
+   * @returns {Promise<Object>} canonical /v1/ip response shape
+   */
+  async ipMe() {
+    return this._request('GET', '/ip/me');
+  }
+
+  /**
+   * Batch IP lookup. Up to 1000 IPs per call.
+   *
+   * @param {string[]} ips - array of IPs
+   * @returns {Promise<{results: Object[]}>}
+   */
+  async ipBatch(ips) {
+    if (!Array.isArray(ips) || ips.length === 0) {
+      throw new InvalidRequestError('ips must be a non-empty array');
+    }
+    if (ips.length > 1000) {
+      throw new InvalidRequestError('ipBatch supports at most 1000 IPs per call');
+    }
+    return this._request('POST', '/ip/batch', {}, { ips });
+  }
 }
 
 module.exports = {