csv2geo-sdk 1.1.0 → 1.3.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.1.0",
-  "description": "Node.js SDK for CSV2GEO Geocoding API — 461M+ addresses, 39 countries, 42 endpoints. Forward, reverse, batch, places, divisions (incl. postcode → boundary), coverage, autocomplete. 3,000 free requests/day.",
+  "version": "1.3.0",
+  "description": "Node.js SDK for CSV2GEO Geocoding API — 461M+ addresses, 39 countries, 45+ endpoints. Forward, reverse, batch, places, boundaries (postcode → polygon, ancestors walk-up, children walk-down, consolidated cities), 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.3.0',
         },
         signal: controller.signal,
       };
@@ -497,7 +497,12 @@ class Client {
     return this._request('GET', '/divisions/random', params);
   }
 
-  /** Full parent/child chain for a division. GET /divisions/hierarchy/{id} */
+  /**
+   * Children of a division (immediate sub-divisions). GET /divisions/hierarchy/{id}
+   *
+   * Note: returns CHILDREN, not ancestors. For walk-UP "part-of" chain, use
+   * `divisionAncestors()`. Kept under the original name for backward compatibility.
+   */
   async divisionHierarchy(divisionId) {
     return this._request('GET', `/divisions/hierarchy/${encodeURIComponent(divisionId)}`);
   }
@@ -507,6 +512,74 @@ class Client {
     return this._request('GET', `/divisions/${encodeURIComponent(divisionId)}`);
   }
 
+  // ─────────────────────────────────────────────────────────
+  // Boundaries (Sprint 1.8)
+  // ─────────────────────────────────────────────────────────
+
+  /**
+   * Walk-up "part-of" chain: input → parent → root.
+   * GET /divisions/ancestors/{id}
+   *
+   * @param {string} divisionId - Overture ID of the leaf division.
+   * @param {object} [options]
+   * @param {string} [options.include] - "geometry" to include each level's polygon.
+   * @param {string} [options.precision] - "low" | "med" (default) | "full".
+   * @param {number} [options.maxDepth] - Hard cap (default 8, max 12).
+   * @returns {Promise<{id: string, depth: number, results: object[]}>}
+   *
+   * @example
+   *   const chain = await client.divisionAncestors(beverlyHillsId, { include: 'geometry' });
+   *   chain.results.forEach(level => console.log(level.subtype, level.name));
+   */
+  async divisionAncestors(divisionId, options = {}) {
+    const params = {};
+    if (options.include)   params.include   = options.include;
+    if (options.precision) params.precision = options.precision;
+    if (options.maxDepth)  params.max_depth = options.maxDepth;
+    return this._request('GET', `/divisions/ancestors/${encodeURIComponent(divisionId)}`, params);
+  }
+
+  /**
+   * Immediate sub-divisions of a division (clearer-named alias of
+   * divisionHierarchy plus optional polygon enrichment).
+   * GET /divisions/children/{id}
+   *
+   * @param {string} divisionId
+   * @param {object} [options]
+   * @param {string} [options.include]   - "geometry" to include polygons.
+   * @param {string} [options.precision] - "low" | "med" (default) | "full".
+   * @param {string} [options.subtype]   - Filter by admin subtype.
+   * @param {number} [options.limit]     - Max children (default 100, max 500).
+   */
+  async divisionChildren(divisionId, options = {}) {
+    const params = {};
+    if (options.include)   params.include   = options.include;
+    if (options.precision) params.precision = options.precision;
+    if (options.subtype)   params.subtype   = options.subtype;
+    if (options.limit)     params.limit     = options.limit;
+    return this._request('GET', `/divisions/children/${encodeURIComponent(divisionId)}`, params);
+  }
+
+  /**
+   * Consolidated entity lookup. Resolves canonical OR member id — e.g. any of
+   * NYC's 5 borough ids returns the canonical "New York City" record + members.
+   * GET /divisions/consolidated/{id}
+   *
+   * @param {string} divisionId
+   * @param {object} [options]
+   * @param {string} [options.include]   - "geometry" for canonical's outline.
+   * @param {string} [options.precision] - "low" | "med" (default) | "full".
+   * @returns {Promise<{canonical: object, members: object[], matched_as: string, source: string}>}
+   *
+   * @throws ApiError(404) when the id is not part of any consolidated entity.
+   */
+  async divisionConsolidated(divisionId, options = {}) {
+    const params = {};
+    if (options.include)   params.include   = options.include;
+    if (options.precision) params.precision = options.precision;
+    return this._request('GET', `/divisions/consolidated/${encodeURIComponent(divisionId)}`, params);
+  }
+
   // ─────────────────────────────────────────────────────────
   // Coverage
   // ─────────────────────────────────────────────────────────
@@ -563,6 +636,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 = {