geocodio-library-node 1.10.0 → 1.13.0

package/lib/__tests__/distance.test.js

@@ -0,0 +1,365 @@
+const Geocodio = require("../index.js");
+const {
+  Coordinate,
+  DistanceMode,
+  DistanceUnits,
+  DistanceOrderBy,
+  DistanceSortOrder
+} = require("../index.js");
+
+describe("Coordinate class", () => {
+  it("Can create coordinate from numbers", () => {
+    const coord = new Coordinate(38.8977, -77.0365);
+    expect(coord.lat).toEqual(38.8977);
+    expect(coord.lng).toEqual(-77.0365);
+    expect(coord.id).toBeUndefined();
+  });
+
+  it("Can create coordinate with id", () => {
+    const coord = new Coordinate(38.8977, -77.0365, "white_house");
+    expect(coord.lat).toEqual(38.8977);
+    expect(coord.lng).toEqual(-77.0365);
+    expect(coord.id).toEqual("white_house");
+  });
+
+  it("Can convert to string format", () => {
+    const coord = new Coordinate(38.8977, -77.0365);
+    expect(coord.toString()).toEqual("38.8977,-77.0365");
+  });
+
+  it("Can convert to string format with id", () => {
+    const coord = new Coordinate(38.8977, -77.0365, "white_house");
+    expect(coord.toString()).toEqual("38.8977,-77.0365,white_house");
+  });
+
+  it("Can convert to object format", () => {
+    const coord = new Coordinate(38.8977, -77.0365);
+    expect(coord.toObject()).toEqual({ lat: 38.8977, lng: -77.0365 });
+  });
+
+  it("Can convert to object format with id", () => {
+    const coord = new Coordinate(38.8977, -77.0365, "white_house");
+    expect(coord.toObject()).toEqual({
+      lat: 38.8977,
+      lng: -77.0365,
+      id: "white_house"
+    });
+  });
+
+  it("Can create from string", () => {
+    const coord = Coordinate.from("38.8977,-77.0365");
+    expect(coord.lat).toEqual(38.8977);
+    expect(coord.lng).toEqual(-77.0365);
+  });
+
+  it("Can create from string with id", () => {
+    const coord = Coordinate.from("38.8977,-77.0365,white_house");
+    expect(coord.lat).toEqual(38.8977);
+    expect(coord.lng).toEqual(-77.0365);
+    expect(coord.id).toEqual("white_house");
+  });
+
+  it("Can create from array", () => {
+    const coord = Coordinate.from([38.8977, -77.0365]);
+    expect(coord.lat).toEqual(38.8977);
+    expect(coord.lng).toEqual(-77.0365);
+  });
+
+  it("Can create from array with id", () => {
+    const coord = Coordinate.from([38.8977, -77.0365, "white_house"]);
+    expect(coord.lat).toEqual(38.8977);
+    expect(coord.lng).toEqual(-77.0365);
+    expect(coord.id).toEqual("white_house");
+  });
+
+  it("Can create from object", () => {
+    const coord = Coordinate.from({ lat: 38.8977, lng: -77.0365 });
+    expect(coord.lat).toEqual(38.8977);
+    expect(coord.lng).toEqual(-77.0365);
+  });
+
+  it("Can create from object with id", () => {
+    const coord = Coordinate.from({
+      lat: 38.8977,
+      lng: -77.0365,
+      id: "white_house"
+    });
+    expect(coord.lat).toEqual(38.8977);
+    expect(coord.lng).toEqual(-77.0365);
+    expect(coord.id).toEqual("white_house");
+  });
+
+  it("Can create from Coordinate instance", () => {
+    const original = new Coordinate(38.8977, -77.0365, "white_house");
+    const coord = Coordinate.from(original);
+    expect(coord).toBe(original);
+  });
+
+  it("Throws error for invalid latitude", () => {
+    expect(() => new Coordinate(100, -77.0365)).toThrow(
+      "Latitude must be between -90 and 90"
+    );
+  });
+
+  it("Throws error for invalid longitude", () => {
+    expect(() => new Coordinate(38.8977, 200)).toThrow(
+      "Longitude must be between -180 and 180"
+    );
+  });
+
+  it("Throws error for non-numeric latitude", () => {
+    expect(() => new Coordinate("not a number", -77.0365)).toThrow(
+      "Latitude must be a number"
+    );
+  });
+
+  it("Throws error for invalid string format", () => {
+    expect(() => Coordinate.fromString("invalid")).toThrow(
+      "Invalid coordinate string"
+    );
+  });
+
+  it("Throws error for non-numeric coordinate values", () => {
+    expect(() => Coordinate.fromString("abc,def")).toThrow(
+      "Invalid coordinate values"
+    );
+  });
+});
+
+describe("Distance enums", () => {
+  it("DistanceMode has correct values", () => {
+    expect(DistanceMode.Straightline).toEqual("straightline");
+    expect(DistanceMode.Driving).toEqual("driving");
+    expect(DistanceMode.Haversine).toEqual("haversine");
+  });
+
+  it("DistanceUnits has correct values", () => {
+    expect(DistanceUnits.Miles).toEqual("miles");
+    expect(DistanceUnits.Kilometers).toEqual("km");
+    expect(DistanceUnits.Km).toEqual("km");
+  });
+
+  it("DistanceOrderBy has correct values", () => {
+    expect(DistanceOrderBy.Distance).toEqual("distance");
+    expect(DistanceOrderBy.Duration).toEqual("duration");
+  });
+
+  it("DistanceSortOrder has correct values", () => {
+    expect(DistanceSortOrder.Asc).toEqual("asc");
+    expect(DistanceSortOrder.Desc).toEqual("desc");
+  });
+});
+
+describe("Distance API", () => {
+  const geocoder = new Geocodio();
+
+  // White House coordinates
+  const whiteHouse = "38.8977,-77.0365,white_house";
+  // Capitol Building
+  const capitol = "38.8899,-77.0091,capitol";
+  // Washington Monument
+  const monument = "38.8895,-77.0353,monument";
+
+  it("Can calculate distance from single origin to destinations", () => {
+    expect.assertions(3);
+
+    return geocoder.distance(whiteHouse, [capitol, monument]).then(response => {
+      expect(response.origin).toBeDefined();
+      expect(response.destinations.length).toEqual(2);
+      const ids = response.destinations.map(d => d.id);
+      expect(ids).toContain("capitol");
+    });
+  });
+
+  it("Can calculate distance with Coordinate objects", () => {
+    expect.assertions(3);
+
+    const origin = new Coordinate(38.8977, -77.0365, "white_house");
+    const destinations = [
+      new Coordinate(38.8899, -77.0091, "capitol"),
+      new Coordinate(38.8895, -77.0353, "monument")
+    ];
+
+    return geocoder.distance(origin, destinations).then(response => {
+      expect(response.origin).toBeDefined();
+      expect(response.destinations.length).toEqual(2);
+      const ids = response.destinations.map(d => d.id);
+      expect(ids).toContain("capitol");
+    });
+  });
+
+  it("Can calculate distance with array format", () => {
+    expect.assertions(3);
+
+    return geocoder
+      .distance(
+        [38.8977, -77.0365, "white_house"],
+        [
+          [38.8899, -77.0091, "capitol"],
+          [38.8895, -77.0353, "monument"]
+        ]
+      )
+      .then(response => {
+        expect(response.origin).toBeDefined();
+        expect(response.destinations.length).toEqual(2);
+        const ids = response.destinations.map(d => d.id);
+        expect(ids).toContain("capitol");
+      });
+  });
+
+  it("Can calculate distance with driving mode", () => {
+    expect.assertions(2);
+
+    return geocoder
+      .distance(whiteHouse, [capitol], { mode: DistanceMode.Driving })
+      .then(response => {
+        expect(response.mode).toEqual("driving");
+        expect(response.destinations[0].duration_seconds).toBeDefined();
+      });
+  });
+
+  it("Can calculate distance in kilometers", () => {
+    expect.assertions(1);
+
+    return geocoder
+      .distance(whiteHouse, [capitol], { units: DistanceUnits.Kilometers })
+      .then(response => {
+        expect(response.destinations[0].distance_km).toBeDefined();
+      });
+  });
+
+  it("Can use haversine mode (maps to straightline)", () => {
+    expect.assertions(1);
+
+    return geocoder
+      .distance(whiteHouse, [capitol], { mode: DistanceMode.Haversine })
+      .then(response => {
+        expect(response.mode).toEqual("straightline");
+      });
+  });
+
+  it("Can limit max results", () => {
+    expect.assertions(1);
+
+    return geocoder
+      .distance(whiteHouse, [capitol, monument], { maxResults: 1 })
+      .then(response => {
+        expect(response.destinations.length).toEqual(1);
+      });
+  });
+});
+
+describe("Distance Matrix API", () => {
+  const geocoder = new Geocodio();
+
+  const origins = [
+    { lat: 38.8977, lng: -77.0365, id: "white_house" },
+    { lat: 38.8899, lng: -77.0091, id: "capitol" }
+  ];
+
+  const destinations = [
+    { lat: 38.8895, lng: -77.0353, id: "monument" },
+    { lat: 38.9072, lng: -77.0369, id: "dupont" }
+  ];
+
+  it("Can calculate distance matrix", () => {
+    expect.assertions(3);
+
+    return geocoder.distanceMatrix(origins, destinations).then(response => {
+      expect(response.mode).toBeDefined();
+      expect(response.results.length).toEqual(2);
+      expect(response.results[0].destinations.length).toBeGreaterThanOrEqual(1);
+    });
+  });
+
+  it("Can calculate distance matrix with string coordinates", () => {
+    expect.assertions(2);
+
+    return geocoder
+      .distanceMatrix(
+        ["38.8977,-77.0365,origin1", "38.8899,-77.0091,origin2"],
+        ["38.8895,-77.0353,dest1"]
+      )
+      .then(response => {
+        expect(response.results.length).toEqual(2);
+        expect(response.results[0].origin.id).toEqual("origin1");
+      });
+  });
+
+  it("Can calculate distance matrix with driving mode", () => {
+    expect.assertions(2);
+
+    return geocoder
+      .distanceMatrix(origins, destinations, { mode: DistanceMode.Driving })
+      .then(response => {
+        expect(response.mode).toEqual("driving");
+        expect(
+          response.results[0].destinations[0].duration_seconds
+        ).toBeDefined();
+      });
+  });
+
+  it("Can calculate distance matrix with filtering options", () => {
+    expect.assertions(1);
+
+    return geocoder
+      .distanceMatrix(origins, destinations, {
+        maxResults: 1,
+        orderBy: DistanceOrderBy.Distance,
+        sortOrder: DistanceSortOrder.Asc
+      })
+      .then(response => {
+        expect(response.results[0].destinations.length).toBeLessThanOrEqual(1);
+      });
+  });
+});
+
+describe("Geocode with distance", () => {
+  const geocoder = new Geocodio();
+
+  it("Can geocode with distance to destinations", () => {
+    expect.assertions(2);
+
+    return geocoder
+      .geocode("1600 Pennsylvania Ave NW, Washington DC", [], null, {
+        destinations: ["38.8899,-77.0091,capitol"]
+      })
+      .then(response => {
+        expect(response.results[0]).toBeDefined();
+        // Note: destinations may or may not be included depending on API version
+        expect(response.results.length).toBeGreaterThan(0);
+      });
+  });
+});
+
+describe("Reverse geocode with distance", () => {
+  const geocoder = new Geocodio();
+
+  it("Can reverse geocode with distance to destinations", () => {
+    expect.assertions(2);
+
+    return geocoder
+      .reverse("38.8977,-77.0365", [], null, {
+        destinations: ["38.8899,-77.0091,capitol"]
+      })
+      .then(response => {
+        expect(response.results[0]).toBeDefined();
+        expect(response.results.length).toBeGreaterThan(0);
+      });
+  });
+});
+
+describe("Distance Matrix Jobs API", () => {
+  const geocoder = new Geocodio();
+
+  it("Can list distance matrix jobs", () => {
+    expect.assertions(1);
+
+    return geocoder.distanceMatrixJobs().then(response => {
+      expect(response.data).toBeDefined();
+    });
+  });
+
+  // Note: Creating, checking status, and deleting jobs is tested in integration
+  // as it requires actual job creation which takes time
+});

package/lib/__tests__/geocodioLibraryNode.test.js

@@ -116,10 +116,10 @@ describe("geocoder", () => {
       .then(response => {
         expect(
           response.results[0].response.results[0].formatted_address
-        ).toEqual("101 W Washington St, Nashville, NC 27856");
+        ).toEqual("116 W Washington St, Nashville, NC 27856");
         expect(
           response.results[1].response.results[0].formatted_address
-        ).toEqual("3034 S 1st St, Garland, TX 75041");
+        ).toEqual("3026 S 1st St, Garland, TX 75041");
       });
   });
 
@@ -134,10 +134,10 @@ describe("geocoder", () => {
       .then(response => {
         expect(
           response.results[0].response.results[0].formatted_address
-        ).toEqual("101 W Washington St, Nashville, NC 27856");
+        ).toEqual("116 W Washington St, Nashville, NC 27856");
         expect(
           response.results[1].response.results[0].formatted_address
-        ).toEqual("3034 S 1st St, Garland, TX 75041");
+        ).toEqual("3026 S 1st St, Garland, TX 75041");
       });
   });
 

package/lib/index.d.ts

@@ -1,4 +1,176 @@
 declare module 'geocodio-library-node' {
+  // Distance API Enums
+  export enum DistanceMode {
+    Straightline = 'straightline',
+    Driving = 'driving',
+    Haversine = 'haversine'  // Alias for straightline (backward compat)
+  }
+
+  export enum DistanceUnits {
+    Miles = 'miles',
+    Kilometers = 'km',
+    Km = 'km'  // Alias
+  }
+
+  export enum DistanceOrderBy {
+    Distance = 'distance',
+    Duration = 'duration'
+  }
+
+  export enum DistanceSortOrder {
+    Asc = 'asc',
+    Desc = 'desc'
+  }
+
+  // Coordinate class for distance calculations
+  export class Coordinate {
+    readonly lat: number;
+    readonly lng: number;
+    readonly id?: string;
+
+    constructor(lat: number, lng: number, id?: string);
+
+    static from(input: CoordinateInput): Coordinate;
+    static fromString(input: string): Coordinate;
+    static fromArray(input: [number, number] | [number, number, string]): Coordinate;
+
+    toString(): string;
+    toObject(): { lat: number; lng: number; id?: string };
+  }
+
+  // Coordinate input types (accept multiple formats)
+  export type CoordinateInput =
+    | Coordinate
+    | string                           // "lat,lng" or "lat,lng,id"
+    | [number, number]                 // [lat, lng]
+    | [number, number, string]         // [lat, lng, id]
+    | { lat: number; lng: number; id?: string };
+
+  // Distance API Response Types
+  export interface DistanceDestination {
+    query: string;
+    location: [number, number];
+    id?: string;
+    distance_miles: number;
+    distance_km: number;
+    duration_seconds?: number;  // Only with driving mode
+  }
+
+  export interface DistanceOrigin {
+    query: string;
+    location: [number, number];
+    id?: string;
+  }
+
+  export interface DistanceResponse {
+    origin: DistanceOrigin;
+    mode: string;
+    destinations: DistanceDestination[];
+  }
+
+  export interface DistanceMatrixResult {
+    origin: DistanceOrigin;
+    destinations: DistanceDestination[];
+  }
+
+  export interface DistanceMatrixResponse {
+    mode: string;
+    results: DistanceMatrixResult[];
+  }
+
+  // Distance options
+  export interface DistanceOptions {
+    mode?: DistanceMode | 'straightline' | 'driving' | 'haversine';
+    units?: DistanceUnits | 'miles' | 'kilometers';
+    maxResults?: number;
+    maxDistance?: number;
+    maxDuration?: number;
+    minDistance?: number;
+    minDuration?: number;
+    orderBy?: DistanceOrderBy | 'distance' | 'duration';
+    sortOrder?: DistanceSortOrder | 'asc' | 'desc';
+  }
+
+  // Distance Job Types
+  export interface DistanceJobResponse {
+    id: number;
+    identifier: string;
+    status: 'ENQUEUED' | 'PROCESSING' | 'COMPLETED' | 'FAILED';
+    name: string;
+    created_at: string;
+    origins_count: number;
+    destinations_count: number;
+    total_calculations: number;
+  }
+
+  export interface DistanceJobStatusResponse {
+    data: {
+      id: number;
+      identifier: string;
+      name: string;
+      status: 'ENQUEUED' | 'PROCESSING' | 'COMPLETED' | 'FAILED';
+      progress: number;
+      download_url?: string;
+      total_calculations: number;
+      calculations_completed: number;
+    };
+  }
+
+  export interface DistanceJobsListResponse {
+    current_page: number;
+    data: Array<{
+      id: number;
+      identifier: string;
+      name: string;
+      status: 'ENQUEUED' | 'PROCESSING' | 'COMPLETED' | 'FAILED';
+      progress: number;
+      total_calculations: number;
+      calculations_completed: number;
+      created_at: string;
+    }>;
+    first_page_url: string;
+    from: number;
+    last_page: number;
+    last_page_url: string;
+    next_page_url: string | null;
+    path: string;
+    per_page: number;
+    prev_page_url: string | null;
+    to: number;
+    total: number;
+  }
+
+  export interface DistanceJobOptions extends DistanceOptions {
+    callbackUrl?: string;
+  }
+
+  // Geocode with distance options
+  export interface GeocodeDistanceOptions {
+    destinations?: CoordinateInput[];
+    distanceMode?: DistanceMode | 'straightline' | 'driving' | 'haversine';
+    distanceUnits?: DistanceUnits | 'miles' | 'kilometers';
+    distanceMaxResults?: number;
+    distanceMaxDistance?: number;
+    distanceMaxDuration?: number;
+    distanceMinDistance?: number;
+    distanceMinDuration?: number;
+    distanceOrderBy?: DistanceOrderBy | 'distance' | 'duration';
+    distanceSortOrder?: DistanceSortOrder | 'asc' | 'desc';
+  }
+
+  // Enhanced geocoded address with distance info
+  export interface GeocodedAddressWithDistance extends GeocodedAddress {
+    destinations?: DistanceDestination[];
+  }
+
+  export interface SingleGeocodeResponseWithDistance extends SingleGeocodeResponse {
+    results: GeocodedAddressWithDistance[];
+  }
+
+  export interface ReverseGeocodeResponseWithDistance extends ReverseGeocodeResponse {
+    results: GeocodedAddressWithDistance[];
+  }
+
   export interface AddressComponents {
     number?: string;
     predirectional?: string;
@@ -17,6 +189,8 @@ declare module 'geocodio-library-node' {
     postal_code?: string; // Alternative to zip used in some API calls
   }
 
+  export type AddressInputComponents = Pick<AddressComponents, "street" | "city" | "county" | "state" | "postal_code" | "country">
+
   export type GeocodeAccuracyType =
     | 'rooftop'
     | 'point'
@@ -224,26 +398,28 @@ declare module 'geocodio-library-node' {
       formatted_address: string;
     };
     results: GeocodedAddress[];
+    _warnings?: string[];
   }
 
-  export interface BatchGeocodeResponse {
-    results: Array<{
-      query: string;
+  export interface BatchGeocodeResponse<Q extends string | AddressInputComponents, T extends Array<Q> | Record<string, Q>> {
+    results: T extends Array<Q> ? Array<{
+      query: Q;
       response: SingleGeocodeResponse;
-    }> | Record<string, {
+    }> : Record<keyof T, {
       response: SingleGeocodeResponse;
     }>;
   }
 
   export interface ReverseGeocodeResponse {
     results: GeocodedAddress[];
+    _warnings?: string[];
   }
 
-  export interface BatchReverseGeocodeResponse {
-    results: Array<{
-      query: string;
+  export interface BatchReverseGeocodeResponse<Q extends string | [number, number], T extends Array<Q> | Record<string, Q>> {
+    results: T extends Array<Q> ? Array<{
+      query: Q;
       response: ReverseGeocodeResponse;
-    }> | Record<string, {
+    }> : Record<keyof T, {
       response: ReverseGeocodeResponse;
     }>;
   }
@@ -259,12 +435,63 @@ declare module 'geocodio-library-node' {
   export default class Geocodio {
     constructor(apiKey?: string, hostname?: string, apiVersion?: string);
 
-    geocode(query: string | AddressComponents, fields?: FieldOption[], limit?: number): Promise<SingleGeocodeResponse>;
-    geocode(query: (string | AddressComponents)[] | Record<string, string | AddressComponents>, fields?: FieldOption[], limit?: number): Promise<BatchGeocodeResponse>;
+    // Geocoding methods
+    geocode(query: string | AddressInputComponents, fields?: FieldOption[], limit?: number): Promise<SingleGeocodeResponse>;
+    geocode<Q extends string | AddressInputComponents, T extends Array<Q> | Record<string, Q>>(query: T, fields?: FieldOption[], limit?: number): Promise<BatchGeocodeResponse<Q, T>>;
 
+    // Geocode with distance
+    geocode(
+      query: string | AddressInputComponents,
+      fields?: FieldOption[],
+      limit?: number,
+      distanceOptions?: GeocodeDistanceOptions
+    ): Promise<SingleGeocodeResponseWithDistance>;
+
+    // Reverse geocoding methods
     reverse(query: string | [number, number], fields?: FieldOption[], limit?: number): Promise<ReverseGeocodeResponse>;
-    reverse(query: (string | [number, number])[] | Record<string, string | [number, number]>, fields?: FieldOption[], limit?: number): Promise<BatchReverseGeocodeResponse>;
+    reverse<Q extends string | [number, number], T extends Array<Q> | Record<string, Q>>(query: T, fields?: FieldOption[], limit?: number): Promise<BatchReverseGeocodeResponse<Q, T>>;
+
+    // Reverse with distance
+    reverse(
+      query: string | [number, number],
+      fields?: FieldOption[],
+      limit?: number,
+      distanceOptions?: GeocodeDistanceOptions
+    ): Promise<ReverseGeocodeResponseWithDistance>;
+
+    // Distance API - Single origin to multiple destinations (GET)
+    distance(
+      origin: CoordinateInput,
+      destinations: CoordinateInput[],
+      options?: DistanceOptions
+    ): Promise<DistanceResponse>;
+
+    // Distance Matrix API - Multiple origins × destinations (POST)
+    distanceMatrix(
+      origins: CoordinateInput[],
+      destinations: CoordinateInput[],
+      options?: DistanceOptions
+    ): Promise<DistanceMatrixResponse>;
+
+    // Async Distance Matrix Job methods
+    createDistanceMatrixJob(
+      name: string,
+      origins: CoordinateInput[] | number,  // Array or list ID
+      destinations: CoordinateInput[] | number,
+      options?: DistanceJobOptions
+    ): Promise<DistanceJobResponse>;
+
+    distanceMatrixJobStatus(id: string | number): Promise<DistanceJobStatusResponse>;
+
+    distanceMatrixJobs(page?: number): Promise<DistanceJobsListResponse>;
+
+    getDistanceMatrixJobResults(id: string | number): Promise<DistanceMatrixResponse>;
+
+    downloadDistanceMatrixJob(id: string | number, filePath: string): Promise<void>;
+
+    deleteDistanceMatrixJob(id: string | number): Promise<void>;
 
+    // List API
     list: {
       create(filename: string, direction: string, format: string, callback: string): Promise<ListResponse>;
       status(listId: number): Promise<unknown>;