csv2geo-sdk 1.0.0

package/README.md

@@ -0,0 +1,208 @@
+# CSV2GEO Node.js SDK
+
+[![npm version](https://img.shields.io/npm/v/csv2geo-sdk.svg)](https://www.npmjs.com/package/csv2geo-sdk)
+[![Node.js versions](https://img.shields.io/node/v/csv2geo-sdk.svg)](https://www.npmjs.com/package/csv2geo-sdk)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+
+Official Node.js SDK for the [CSV2GEO Geocoding API](https://csv2geo.com) - fast, accurate geocoding powered by 446M+ addresses worldwide.
+
+## Installation
+
+```bash
+npm install csv2geo-sdk
+```
+
+## Quick Start
+
+```javascript
+const { Client } = require('csv2geo-sdk');
+
+// Initialize with your API key
+const client = new Client('your_api_key');
+
+// Forward geocoding (address → coordinates)
+const result = await client.geocode('1600 Pennsylvania Ave, Washington DC');
+if (result) {
+  console.log(`Lat: ${result.lat}, Lng: ${result.lng}`);
+  console.log(`Address: ${result.formattedAddress}`);
+}
+
+// Reverse geocoding (coordinates → address)
+const result = await client.reverse(38.8977, -77.0365);
+if (result) {
+  console.log(`Address: ${result.formattedAddress}`);
+}
+```
+
+## Features
+
+- **Forward geocoding** - Convert addresses to coordinates
+- **Reverse geocoding** - Convert coordinates to addresses
+- **Batch processing** - Geocode up to 10,000 addresses per request
+- **Auto-retry** - Automatic retry on rate limits
+- **TypeScript support** - Full type definitions included
+- **Zero dependencies** - Uses native `fetch` (Node.js 18+)
+
+## API Reference
+
+### Initialize Client
+
+```javascript
+const { Client } = require('csv2geo-sdk');
+
+const client = new Client('your_api_key', {
+  baseUrl: 'https://api.csv2geo.com/v1',  // optional
+  timeout: 30000,  // optional, milliseconds
+  autoRetry: true,  // optional, retry on rate limit
+});
+```
+
+### Forward Geocoding
+
+```javascript
+// Simple - returns best match or null
+const result = await client.geocode('1600 Pennsylvania Ave, Washington DC');
+
+// With country filter
+const result = await client.geocode('123 Main St', { country: 'US' });
+
+// Full response with all matches
+const response = await client.geocodeFull('1600 Pennsylvania Ave');
+for (const result of response.results) {
+  console.log(`${result.formattedAddress}: ${result.accuracyScore}`);
+}
+```
+
+### Reverse Geocoding
+
+```javascript
+// Simple - returns best match or null
+const result = await client.reverse(38.8977, -77.0365);
+
+// Full response with all matches
+const response = await client.reverseFull(38.8977, -77.0365);
+```
+
+### Batch Geocoding
+
+```javascript
+// Geocode multiple addresses (up to 10,000)
+const addresses = [
+  '1600 Pennsylvania Ave, Washington DC',
+  '350 Fifth Avenue, New York, NY',
+  '1 Infinite Loop, Cupertino, CA',
+];
+
+const results = await client.geocodeBatch(addresses);
+for (const response of results) {
+  const best = response.results[0];
+  if (best) {
+    console.log(`${response.query}: ${best.lat}, ${best.lng}`);
+  } else {
+    console.log(`${response.query}: Not found`);
+  }
+}
+```
+
+### Batch Reverse Geocoding
+
+```javascript
+// Reverse geocode multiple coordinates
+const coordinates = [
+  { lat: 38.8977, lng: -77.0365 },
+  { lat: 40.7484, lng: -73.9857 },
+];
+
+const results = await client.reverseBatch(coordinates);
+for (const response of results) {
+  const best = response.results[0];
+  if (best) {
+    console.log(best.formattedAddress);
+  }
+}
+```
+
+### GeocodeResult Object
+
+```javascript
+const result = await client.geocode('1600 Pennsylvania Ave, Washington DC');
+
+// Coordinates
+result.lat              // 38.8977
+result.lng              // -77.0365
+
+// Address
+result.formattedAddress  // "1600 PENNSYLVANIA AVE NW, WASHINGTON, DC 20500, US"
+result.accuracy          // "rooftop"
+result.accuracyScore     // 1.0
+
+// Components
+result.components.houseNumber  // "1600"
+result.components.street       // "PENNSYLVANIA AVE NW"
+result.components.city         // "WASHINGTON"
+result.components.state        // "DC"
+result.components.postcode     // "20500"
+result.components.country      // "US"
+```
+
+## Error Handling
+
+```javascript
+const { Client, AuthenticationError, RateLimitError, InvalidRequestError } = require('csv2geo-sdk');
+
+const client = new Client('your_api_key');
+
+try {
+  const result = await client.geocode('123 Main St');
+} catch (err) {
+  if (err instanceof AuthenticationError) {
+    console.log(`Invalid API key: ${err.message}`);
+  } else if (err instanceof RateLimitError) {
+    console.log(`Rate limited. Retry after ${err.retryAfter} seconds`);
+  } else if (err instanceof InvalidRequestError) {
+    console.log(`Invalid request: ${err.message}`);
+  }
+}
+```
+
+## Rate Limits
+
+The client tracks rate limit headers automatically:
+
+```javascript
+await client.geocode('123 Main St');
+
+console.log(client.rateLimit);            // Max requests per minute
+console.log(client.rateLimitRemaining);   // Requests remaining
+console.log(client.rateLimitReset);       // Unix timestamp when limit resets
+```
+
+With `autoRetry: true` (default), the client automatically waits and retries when rate limited.
+
+## TypeScript
+
+Full TypeScript support is included:
+
+```typescript
+import { Client, GeocodeResult, GeocodeResponse } from 'csv2geo-sdk';
+
+const client = new Client('your_api_key');
+const result: GeocodeResult | null = await client.geocode('123 Main St');
+```
+
+## Requirements
+
+- Node.js 16+ (uses native `fetch`)
+
+## Get Your API Key
+
+Sign up at [csv2geo.com](https://csv2geo.com) to get your API key.
+
+## Documentation
+
+- [API Documentation](https://acenji.github.io/csv2geo-api/docs/)
+- [OpenAPI Specification](https://github.com/acenji/csv2geo-api/blob/main/openapi.yaml)
+
+## License
+
+MIT License - see [LICENSE](https://github.com/acenji/csv2geo-api/blob/main/LICENSE) for details.

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "csv2geo-sdk",
+  "version": "1.0.0",
+  "description": "Node.js SDK for CSV2GEO Geocoding API",
+  "main": "src/index.js",
+  "types": "src/index.d.ts",
+  "files": [
+    "src/**/*"
+  ],
+  "scripts": {
+    "test": "node --test test/*.test.js",
+    "lint": "eslint src/"
+  },
+  "keywords": [
+    "geocoding",
+    "geocode",
+    "address",
+    "latitude",
+    "longitude",
+    "maps",
+    "csv2geo",
+    "geolocation"
+  ],
+  "author": "Scale Campaign <admin@csv2geo.com>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/acenji/csv2geo-api.git"
+  },
+  "bugs": {
+    "url": "https://github.com/acenji/csv2geo-api/issues"
+  },
+  "homepage": "https://csv2geo.com",
+  "engines": {
+    "node": ">=16.0.0"
+  },
+  "devDependencies": {
+    "eslint": "^8.0.0"
+  }
+}

package/src/errors.js

@@ -0,0 +1,75 @@
+/**
+ * Custom errors for CSV2GEO SDK
+ */
+
+/**
+ * Base error class for CSV2GEO SDK
+ */
+class CSV2GEOError extends Error {
+  constructor(message, code = null, status = null) {
+    super(message);
+    this.name = 'CSV2GEOError';
+    this.code = code;
+    this.status = status;
+  }
+}
+
+/**
+ * Raised when API key is missing, invalid, or revoked
+ */
+class AuthenticationError extends CSV2GEOError {
+  constructor(message, code = null, status = 401) {
+    super(message, code, status);
+    this.name = 'AuthenticationError';
+  }
+}
+
+/**
+ * Raised when rate limit is exceeded
+ */
+class RateLimitError extends CSV2GEOError {
+  constructor(message, code = null, status = 429, retryAfter = null) {
+    super(message, code, status);
+    this.name = 'RateLimitError';
+    this.retryAfter = retryAfter;
+  }
+}
+
+/**
+ * Raised when request parameters are invalid
+ */
+class InvalidRequestError extends CSV2GEOError {
+  constructor(message, code = null, status = 400) {
+    super(message, code, status);
+    this.name = 'InvalidRequestError';
+  }
+}
+
+/**
+ * Raised when API key lacks required permission
+ */
+class PermissionError extends CSV2GEOError {
+  constructor(message, code = null, status = 403) {
+    super(message, code, status);
+    this.name = 'PermissionError';
+  }
+}
+
+/**
+ * Raised for general API errors
+ */
+class APIError extends CSV2GEOError {
+  constructor(message, code = null, status = 500) {
+    super(message, code, status);
+    this.name = 'APIError';
+  }
+}
+
+module.exports = {
+  CSV2GEOError,
+  AuthenticationError,
+  RateLimitError,
+  InvalidRequestError,
+  PermissionError,
+  APIError,
+};

package/src/index.d.ts

@@ -0,0 +1,126 @@
+/**
+ * CSV2GEO Node.js SDK Type Definitions
+ */
+
+export interface ClientOptions {
+  /** API base URL (default: https://api.csv2geo.com/v1) */
+  baseUrl?: string;
+  /** Request timeout in milliseconds (default: 30000) */
+  timeout?: number;
+  /** Auto-retry on rate limit (default: true) */
+  autoRetry?: boolean;
+}
+
+export interface GeocodeOptions {
+  /** Limit to specific country (ISO 3166-1 alpha-2) */
+  country?: string;
+}
+
+export interface AddressComponents {
+  houseNumber?: string;
+  street?: string;
+  unit?: string;
+  city?: string;
+  state?: string;
+  postcode?: string;
+  country?: string;
+}
+
+export interface GeocodeResult {
+  formattedAddress: string;
+  lat: number;
+  lng: number;
+  accuracy: string;
+  accuracyScore: number;
+  components: AddressComponents;
+}
+
+export interface GeocodeResponse {
+  query: string | { lat: number; lng: number };
+  results: GeocodeResult[];
+}
+
+export interface Coordinate {
+  lat: number;
+  lng: number;
+}
+
+export class Client {
+  /** Max requests per minute */
+  rateLimit: string | null;
+  /** Requests remaining in current window */
+  rateLimitRemaining: string | null;
+  /** Unix timestamp when limit resets */
+  rateLimitReset: string | null;
+
+  /**
+   * Create a new CSV2GEO client
+   * @param apiKey Your CSV2GEO API key
+   * @param options Configuration options
+   */
+  constructor(apiKey: string, options?: ClientOptions);
+
+  /**
+   * Geocode a single address
+   * @param address The address to geocode
+   * @param options Options
+   * @returns Best result or null if not found
+   */
+  geocode(address: string, options?: GeocodeOptions): Promise<GeocodeResult | null>;
+
+  /**
+   * Geocode with full response
+   * @param address The address to geocode
+   * @param options Options
+   * @returns Full response with all results
+   */
+  geocodeFull(address: string, options?: GeocodeOptions): Promise<GeocodeResponse>;
+
+  /**
+   * Reverse geocode coordinates
+   * @param lat Latitude
+   * @param lng Longitude
+   * @returns Best result or null if not found
+   */
+  reverse(lat: number, lng: number): Promise<GeocodeResult | null>;
+
+  /**
+   * Reverse geocode with full response
+   * @param lat Latitude
+   * @param lng Longitude
+   * @returns Full response with all results
+   */
+  reverseFull(lat: number, lng: number): Promise<GeocodeResponse>;
+
+  /**
+   * Batch geocode multiple addresses
+   * @param addresses Array of addresses (max 10,000)
+   * @returns Array of responses
+   */
+  geocodeBatch(addresses: string[]): Promise<GeocodeResponse[]>;
+
+  /**
+   * Batch reverse geocode multiple coordinates
+   * @param coordinates Array of coordinates (max 10,000)
+   * @returns Array of responses
+   */
+  reverseBatch(coordinates: Coordinate[]): Promise<GeocodeResponse[]>;
+}
+
+export class CSV2GEOError extends Error {
+  code: string | null;
+  status: number | null;
+  constructor(message: string, code?: string | null, status?: number | null);
+}
+
+export class AuthenticationError extends CSV2GEOError {}
+
+export class RateLimitError extends CSV2GEOError {
+  retryAfter: number | null;
+}
+
+export class InvalidRequestError extends CSV2GEOError {}
+
+export class PermissionError extends CSV2GEOError {}
+
+export class APIError extends CSV2GEOError {}

package/src/index.js

@@ -0,0 +1,296 @@
+/**
+ * CSV2GEO Node.js SDK
+ *
+ * Fast, accurate geocoding powered by 446M+ addresses worldwide.
+ *
+ * @example
+ * const { Client } = require('csv2geo');
+ *
+ * const client = new Client('your_api_key');
+ * const result = await client.geocode('1600 Pennsylvania Ave, Washington DC');
+ * console.log(result.lat, result.lng);
+ */
+
+const {
+  CSV2GEOError,
+  AuthenticationError,
+  RateLimitError,
+  InvalidRequestError,
+  PermissionError,
+  APIError,
+} = require('./errors');
+
+const DEFAULT_BASE_URL = 'https://api.csv2geo.com/v1';
+const DEFAULT_TIMEOUT = 30000;
+const MAX_RETRIES = 3;
+
+/**
+ * CSV2GEO API Client
+ */
+class Client {
+  /**
+   * Create a new CSV2GEO client
+   * @param {string} apiKey - Your CSV2GEO API key
+   * @param {Object} [options] - Configuration options
+   * @param {string} [options.baseUrl] - API base URL
+   * @param {number} [options.timeout] - Request timeout in milliseconds
+   * @param {boolean} [options.autoRetry] - Auto-retry on rate limit (default: true)
+   */
+  constructor(apiKey, options = {}) {
+    if (!apiKey) {
+      throw new Error('API key is required');
+    }
+
+    this.apiKey = apiKey;
+    this.baseUrl = (options.baseUrl || DEFAULT_BASE_URL).replace(/\/$/, '');
+    this.timeout = options.timeout || DEFAULT_TIMEOUT;
+    this.autoRetry = options.autoRetry !== false;
+
+    // Rate limit tracking
+    this.rateLimit = null;
+    this.rateLimitRemaining = null;
+    this.rateLimitReset = null;
+  }
+
+  /**
+   * Make an API request
+   * @private
+   */
+  async _request(method, endpoint, params = {}, body = null, retryCount = 0) {
+    const url = new URL(`${this.baseUrl}${endpoint}`);
+
+    // Add query parameters
+    Object.entries(params).forEach(([key, value]) => {
+      if (value !== undefined && value !== null) {
+        url.searchParams.append(key, value);
+      }
+    });
+
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), this.timeout);
+
+    try {
+      const fetchOptions = {
+        method,
+        headers: {
+          'Authorization': `Bearer ${this.apiKey}`,
+          'Content-Type': 'application/json',
+          'User-Agent': 'csv2geo-node/1.0.0',
+        },
+        signal: controller.signal,
+      };
+
+      if (body) {
+        fetchOptions.body = JSON.stringify(body);
+      }
+
+      const response = await fetch(url.toString(), fetchOptions);
+      clearTimeout(timeoutId);
+
+      // Update rate limit info
+      this.rateLimit = response.headers.get('X-RateLimit-Limit');
+      this.rateLimitRemaining = response.headers.get('X-RateLimit-Remaining');
+      this.rateLimitReset = response.headers.get('X-RateLimit-Reset');
+
+      const data = await response.json();
+
+      if (response.ok) {
+        return data;
+      }
+
+      // Handle errors
+      const error = data.error || {};
+      const code = error.code || 'unknown';
+      const message = error.message || 'Unknown error';
+      const status = error.status || response.status;
+
+      if (response.status === 401) {
+        throw new AuthenticationError(message, code, status);
+      } else if (response.status === 403) {
+        throw new PermissionError(message, code, status);
+      } else if (response.status === 429) {
+        const retryAfter = parseInt(response.headers.get('Retry-After') || '60', 10);
+        const rateLimitError = new RateLimitError(message, code, status, retryAfter);
+
+        if (this.autoRetry && retryCount < MAX_RETRIES) {
+          await this._sleep(Math.min(retryAfter * 1000, 60000));
+          return this._request(method, endpoint, params, body, retryCount + 1);
+        }
+        throw rateLimitError;
+      } else if (response.status === 400) {
+        throw new InvalidRequestError(message, code, status);
+      } else {
+        throw new APIError(message, code, status);
+      }
+    } catch (err) {
+      clearTimeout(timeoutId);
+
+      if (err.name === 'AbortError') {
+        throw new APIError('Request timed out', 'timeout');
+      }
+      if (err instanceof CSV2GEOError) {
+        throw err;
+      }
+      throw new APIError(err.message, 'network_error');
+    }
+  }
+
+  /**
+   * Sleep helper
+   * @private
+   */
+  _sleep(ms) {
+    return new Promise(resolve => setTimeout(resolve, ms));
+  }
+
+  /**
+   * Geocode a single address
+   * @param {string} address - The address to geocode
+   * @param {Object} [options] - Options
+   * @param {string} [options.country] - Limit to specific country (ISO 3166-1 alpha-2)
+   * @returns {Promise<GeocodeResult|null>} Best result or null if not found
+   *
+   * @example
+   * const result = await client.geocode('1600 Pennsylvania Ave, Washington DC');
+   * if (result) {
+   *   console.log(result.lat, result.lng);
+   * }
+   */
+  async geocode(address, options = {}) {
+    const params = { q: address };
+    if (options.country) params.country = options.country;
+
+    const data = await this._request('GET', '/geocode', params);
+    const results = data.results || [];
+    return results.length > 0 ? this._parseResult(results[0]) : null;
+  }
+
+  /**
+   * Geocode with full response
+   * @param {string} address - The address to geocode
+   * @param {Object} [options] - Options
+   * @returns {Promise<GeocodeResponse>} Full response with all results
+   */
+  async geocodeFull(address, options = {}) {
+    const params = { q: address };
+    if (options.country) params.country = options.country;
+
+    const data = await this._request('GET', '/geocode', params);
+    return {
+      query: data.query,
+      results: (data.results || []).map(r => this._parseResult(r)),
+    };
+  }
+
+  /**
+   * Reverse geocode coordinates
+   * @param {number} lat - Latitude
+   * @param {number} lng - Longitude
+   * @returns {Promise<GeocodeResult|null>} Best result or null if not found
+   *
+   * @example
+   * const result = await client.reverse(38.8977, -77.0365);
+   * if (result) {
+   *   console.log(result.formattedAddress);
+   * }
+   */
+  async reverse(lat, lng) {
+    const data = await this._request('GET', '/reverse', { lat, lng });
+    const results = data.results || [];
+    return results.length > 0 ? this._parseResult(results[0]) : null;
+  }
+
+  /**
+   * Reverse geocode with full response
+   * @param {number} lat - Latitude
+   * @param {number} lng - Longitude
+   * @returns {Promise<GeocodeResponse>} Full response with all results
+   */
+  async reverseFull(lat, lng) {
+    const data = await this._request('GET', '/reverse', { lat, lng });
+    return {
+      query: data.query,
+      results: (data.results || []).map(r => this._parseResult(r)),
+    };
+  }
+
+  /**
+   * Batch geocode multiple addresses
+   * @param {string[]} addresses - Array of addresses (max 10,000)
+   * @returns {Promise<GeocodeResponse[]>} Array of responses
+   *
+   * @example
+   * const results = await client.geocodeBatch([
+   *   '1600 Pennsylvania Ave, Washington DC',
+   *   '350 Fifth Avenue, New York, NY',
+   * ]);
+   */
+  async geocodeBatch(addresses) {
+    if (addresses.length > 10000) {
+      throw new InvalidRequestError('Maximum 10,000 addresses per batch request');
+    }
+
+    const data = await this._request('POST', '/geocode', {}, { addresses });
+    return (data.results || []).map(r => ({
+      query: r.query,
+      results: (r.results || []).map(res => this._parseResult(res)),
+    }));
+  }
+
+  /**
+   * Batch reverse geocode multiple coordinates
+   * @param {Array<{lat: number, lng: number}>} coordinates - Array of coordinates (max 10,000)
+   * @returns {Promise<GeocodeResponse[]>} Array of responses
+   *
+   * @example
+   * const results = await client.reverseBatch([
+   *   { lat: 38.8977, lng: -77.0365 },
+   *   { lat: 40.7484, lng: -73.9857 },
+   * ]);
+   */
+  async reverseBatch(coordinates) {
+    if (coordinates.length > 10000) {
+      throw new InvalidRequestError('Maximum 10,000 coordinates per batch request');
+    }
+
+    const data = await this._request('POST', '/reverse', {}, { coordinates });
+    return (data.results || []).map(r => ({
+      query: r.query,
+      results: (r.results || []).map(res => this._parseResult(res)),
+    }));
+  }
+
+  /**
+   * Parse API result into GeocodeResult
+   * @private
+   */
+  _parseResult(data) {
+    const location = data.location || {};
+    return {
+      formattedAddress: data.formatted_address,
+      lat: location.lat,
+      lng: location.lng,
+      accuracy: data.accuracy,
+      accuracyScore: data.accuracy_score,
+      components: {
+        houseNumber: data.components?.house_number,
+        street: data.components?.street,
+        unit: data.components?.unit,
+        city: data.components?.city,
+        state: data.components?.state,
+        postcode: data.components?.postcode,
+        country: data.components?.country,
+      },
+    };
+  }
+}
+
+module.exports = {
+  Client,
+  CSV2GEOError,
+  AuthenticationError,
+  RateLimitError,
+  InvalidRequestError,
+  PermissionError,
+  APIError,
+};