geocodio-library-node 2.0.0 → 2.2.0

package/README.md

@@ -1,5 +1,5 @@
 # geocod.io Node library [![NPM version][npm-image]][npm-url]
-> Library for performing forward and reverse address geocoding for addresses or coordinates in the US and Canada, with support for distance calculations.
+> Library for performing forward and reverse address geocoding for addresses or coordinates in the US, Canada, Mexico and the UK, with support for distance calculations.
 
 <!-- toc -->
 
@@ -10,6 +10,7 @@
   * [Field appends](#field-appends)
   * [Address components](#address-components)
   * [Limit results](#limit-results)
+  * [Warnings](#warnings)
   * [Distance calculation](#distance-calculation)
   * [Distance matrix](#distance-matrix)
   * [Async distance jobs](#async-distance-jobs)
@@ -125,6 +126,7 @@ To batch geocode, simply pass an array of addresses or coordinates instead of a
 geocoder.geocode([
       '1109 N Highland St, Arlington VA',
       '525 University Ave, Toronto, ON, Canada',
+      '10 Downing St, London, United Kingdom',
       '4410 S Highway 17 92, Casselberry FL',
       '15000 NE 24th Street, Redmond WA',
       '17015 Walnut Grove Drive, Morgan Hill CA'
@@ -145,9 +147,10 @@ geocoder.reverse([
 geocoder.geocode({
       'MyId1': '1109 N Highland St, Arlington VA',
       'MyId2': '525 University Ave, Toronto, ON, Canada',
-      'MyId3': '4410 S Highway 17 92, Casselberry FL',
-      'MyId4': '15000 NE 24th Street, Redmond WA',
-      'MyId5': '17015 Walnut Grove Drive, Morgan Hill CA'
+      'MyId3': '10 Downing St, London, United Kingdom',
+      'MyId4': '4410 S Highway 17 92, Casselberry FL',
+      'MyId5': '15000 NE 24th Street, Redmond WA',
+      'MyId6': '17015 Walnut Grove Drive, Morgan Hill CA'
   })
   .then(response => { ... })
   .catch(err => { ... });
@@ -155,7 +158,7 @@ geocoder.geocode({
 
 ### Field appends
 
-Geocodio allows you to append additional data points such as congressional districts, census codes, timezone, ACS survey results and [much much more](https://www.geocod.io/docs/#fields).
+Geocodio allows you to append additional data points such as congressional districts, census codes, timezone, ACS survey results, UK constituencies and wards, and [much much more](https://www.geocod.io/docs/#fields).
 
 To request additional fields, simply supply them as an array as the second parameter
 
@@ -173,6 +176,12 @@ geocoder.geocode(
 geocoder.reverse('38.9002898,-76.9990361', ['census2010'])
   .then(response => { ... })
   .catch(err => { ... });
+
+// United Kingdom addresses support UK-specific appends such as Westminster and
+// devolved parliament constituencies, and local authority wards
+geocoder.geocode('10 Downing St, London, United Kingdom', ['uk-westminster', 'uk-local'])
+  .then(response => { ... })
+  .catch(err => { ... });
 ```
 
 ### Address components
@@ -201,6 +210,12 @@ geocoder.geocode([
           state_province: 'ON',
           country: 'Canada',
       },
+      {
+          street: '10 Downing St',
+          city: 'London',
+          postal_code: 'SW1A 2AA',
+          country: 'United Kingdom',
+      },
   ])
   .then(response => { ... })
   .catch(err => { ... });
@@ -222,6 +237,46 @@ geocoder.reverse('38.9002898,-76.9990361', ['timezone'], 5)
   .catch(err => { ... });
 ```
 
+### Warnings
+
+The API reports non-fatal advisories under a `_warnings` key — a misspelled field name, an unexpected query parameter, a superseded API version, or an append that had to be skipped. The request still succeeds, so nothing is thrown; the warnings simply ride along with the response.
+
+Responses are resolved decoded and verbatim, so warnings are read straight off the response. The key is only present when there is at least one warning, so always fall back to an empty array:
+
+```javascript
+geocoder.geocode('1109 N Highland St, Arlington, VA', ['congress'])
+  .then(response => {
+    (response._warnings || []).forEach(warning => console.warn(warning));
+    // "The field congress is not recognized. Did you mean cd?"
+  });
+```
+
+Warnings show up in a few places, depending on what raised them:
+
+| Where | Applies to |
+| -- | -- |
+| `response._warnings` | Single `geocode(...)` and `reverse(...)`, and the `list` and distance matrix job methods |
+| `response.results[i].response._warnings` | Batch `geocode(...)` and `reverse(...)` — warnings are attached per address |
+| `response.results[i]._warnings` | An individual geocoding result, e.g. an `ffiec` append skipped because the match is not street-level |
+
+All of these are typed as an optional `_warnings?: Warnings` (a `string[]`) in the TypeScript definitions.
+
+Warnings are also attached to error responses, where they are available on the thrown error as `warnings` (always an array, empty when the API sent none):
+
+```javascript
+geocoder.geocode('1109 N Highland St', ['congress'])
+  .catch(err => {
+    console.error(err.message); // "Could not geocode address. Postal code or city required."
+    console.error(err.code);    // 422
+
+    err.warnings.forEach(warning => console.warn(warning));
+    // "The field congress is not recognized. Did you mean cd?"
+  });
+```
+
+> [!TIP]
+> Warnings are worth logging during development — they are how the API tells you a field append was silently skipped, which otherwise looks like missing data.
+
 ### Distance calculations
 
 Calculate distances from a single origin to multiple destinations, or compute full distance matrices.

package/lib/__tests__/geocodioLibraryNode.test.js

@@ -48,12 +48,13 @@ describe("geocoder", () => {
   });
 
   it("Can batch forward geocode", () => {
-    expect.assertions(2);
+    expect.assertions(3);
 
     return geocoder
       .geocode([
         "1109 N Highland St, Arlington VA",
-        "525 University Ave, Toronto, ON, Canada"
+        "525 University Ave, Toronto, ON, Canada",
+        "10 Downing St, London, United Kingdom"
       ])
       .then(response => {
         expect(
@@ -62,6 +63,9 @@ describe("geocoder", () => {
         expect(
           response.results[1].response.results[0].formatted_address
         ).toEqual("525 University Ave, Toronto, ON M5G");
+        expect(
+          response.results[2].response.results[0].formatted_address
+        ).toEqual("10 Downing St, London SW1A 2AA");
       });
   });
 
@@ -116,7 +120,7 @@ describe("geocoder", () => {
       .then(response => {
         expect(
           response.results[0].response.results[0].formatted_address
-        ).toEqual("116 W Washington St, Nashville, NC 27856");
+        ).toEqual("100 E Washington St, Nashville, NC 27856");
         expect(
           response.results[1].response.results[0].formatted_address
         ).toEqual("3026 S 1st St, Garland, TX 75041");
@@ -134,7 +138,7 @@ describe("geocoder", () => {
       .then(response => {
         expect(
           response.results[0].response.results[0].formatted_address
-        ).toEqual("116 W Washington St, Nashville, NC 27856");
+        ).toEqual("100 E Washington St, Nashville, NC 27856");
         expect(
           response.results[1].response.results[0].formatted_address
         ).toEqual("3026 S 1st St, Garland, TX 75041");
@@ -185,6 +189,24 @@ describe("geocoder", () => {
       });
   });
 
+  it("Can append UK-specific fields", () => {
+    expect.assertions(2);
+
+    return geocoder
+      .geocode("10 Downing St, London, United Kingdom", [
+        "uk-westminster",
+        "uk-local"
+      ])
+      .then(response => {
+        expect(response.results[0].fields.uk_westminster[0].name).toEqual(
+          "Cities of London and Westminster"
+        );
+        expect(response.results[0].fields.uk_local[0].district_type).toEqual(
+          "ward"
+        );
+      });
+  });
+
   it("Can limit results", () => {
     expect.assertions(1);
 

package/lib/__tests__/warnings.test.js

@@ -0,0 +1,316 @@
+const axios = require("axios");
+const Geocodio = require("../index.js");
+
+/*
+ * Warnings passthrough
+ *
+ * The API reports non-fatal advisories under a `_warnings` key -- an
+ * unrecognized field name, a superseded API version, an append that was
+ * skipped. The library resolves with the decoded response body verbatim, so
+ * the key is already available to callers. These tests lock that in: they
+ * fail if a future refactor drops the key on any response shape.
+ *
+ * The shapes are the ones the OpenAPI specification models (see the
+ * `Warnings` schema): top-level on single geocode/reverse, per result,
+ * per batch item, and on the lists and distance-jobs responses.
+ */
+
+const respondWith = (method, data) =>
+  jest.spyOn(axios, method).mockResolvedValue({ status: 200, data });
+
+const rejectWith = (method, status, data) => {
+  const error = new Error(`Request failed with status code ${status}`);
+  error.response = { status, data };
+
+  return jest.spyOn(axios, method).mockRejectedValue(error);
+};
+
+describe("warnings", () => {
+  const geocoder = new Geocodio("test-key");
+
+  afterEach(() => {
+    jest.restoreAllMocks();
+  });
+
+  describe("geocoding responses", () => {
+    it("preserves top-level warnings on a single forward geocode", async () => {
+      respondWith("get", {
+        results: [
+          { formatted_address: "1109 N Highland St, Arlington, VA 22201" }
+        ],
+        _warnings: ["The field congress is not recognized. Did you mean cd?"]
+      });
+
+      const response = await geocoder.geocode(
+        "1109 N Highland St, Arlington VA",
+        ["congress"]
+      );
+
+      expect(response._warnings).toEqual([
+        "The field congress is not recognized. Did you mean cd?"
+      ]);
+    });
+
+    it("preserves top-level warnings on a single reverse geocode", async () => {
+      respondWith("get", {
+        results: [
+          { formatted_address: "1109 N Highland St, Arlington, VA 22201" }
+        ],
+        _warnings: [
+          "Ignoring parameter zipcode as it was not expected. Did you mean postal_code?"
+        ]
+      });
+
+      const response = await geocoder.reverse("38.886665,-77.094733");
+
+      expect(response._warnings).toEqual([
+        "Ignoring parameter zipcode as it was not expected. Did you mean postal_code?"
+      ]);
+    });
+
+    it("preserves per-result warnings", async () => {
+      respondWith("get", {
+        results: [
+          {
+            formatted_address: "Arlington, VA 22201",
+            accuracy_type: "place",
+            _warnings: [
+              "ffiec field was skipped since result is not street-level"
+            ]
+          }
+        ]
+      });
+
+      const response = await geocoder.geocode("22201", ["ffiec"]);
+
+      expect(response.results[0]._warnings).toEqual([
+        "ffiec field was skipped since result is not street-level"
+      ]);
+    });
+
+    it("preserves per-item warnings on a batch forward geocode", async () => {
+      const item = query => ({
+        query,
+        response: {
+          results: [{ formatted_address: query }],
+          _warnings: ["The field congress is not recognized. Did you mean cd?"]
+        }
+      });
+
+      respondWith("post", {
+        results: [
+          item("1109 N Highland St, Arlington VA"),
+          item("525 University Ave, Toronto, ON, Canada")
+        ]
+      });
+
+      const response = await geocoder.geocode(
+        [
+          "1109 N Highland St, Arlington VA",
+          "525 University Ave, Toronto, ON, Canada"
+        ],
+        ["congress"]
+      );
+
+      expect(response.results[0].response._warnings).toEqual([
+        "The field congress is not recognized. Did you mean cd?"
+      ]);
+      expect(response.results[1].response._warnings).toEqual([
+        "The field congress is not recognized. Did you mean cd?"
+      ]);
+    });
+
+    it("preserves per-item warnings on a batch reverse geocode", async () => {
+      respondWith("post", {
+        results: [
+          {
+            query: "35.9746000,-77.9658000",
+            response: {
+              results: [
+                {
+                  formatted_address: "101 W Washington St, Nashville, NC 27856"
+                }
+              ],
+              _warnings: [
+                "There is a newer API version available, please consider upgrading to v2."
+              ]
+            }
+          }
+        ]
+      });
+
+      const response = await geocoder.reverse(["35.9746000,-77.9658000"]);
+
+      expect(response.results[0].response._warnings).toEqual([
+        "There is a newer API version available, please consider upgrading to v2."
+      ]);
+    });
+
+    it("does not invent a warnings key when the API sends none", async () => {
+      respondWith("get", {
+        results: [
+          { formatted_address: "1109 N Highland St, Arlington, VA 22201" }
+        ]
+      });
+
+      const response = await geocoder.geocode(
+        "1109 N Highland St, Arlington VA"
+      );
+
+      expect(response).not.toHaveProperty("_warnings");
+      expect(response._warnings || []).toEqual([]);
+    });
+  });
+
+  describe("lists responses", () => {
+    it("preserves warnings on list status", async () => {
+      respondWith("get", {
+        id: 42,
+        status: { state: "COMPLETED" },
+        _warnings: [
+          "The fields parameter should contain a comma-separated list of fields instead of an array"
+        ]
+      });
+
+      const response = await geocoder.list.status(42);
+
+      expect(response._warnings).toEqual([
+        "The fields parameter should contain a comma-separated list of fields instead of an array"
+      ]);
+    });
+
+    it("preserves warnings when listing all lists", async () => {
+      respondWith("get", {
+        data: [],
+        total: 0,
+        _warnings: [
+          "The fields parameter should contain a comma-separated list of fields instead of an array"
+        ]
+      });
+
+      const response = await geocoder.list.all();
+
+      expect(response._warnings).toEqual([
+        "The fields parameter should contain a comma-separated list of fields instead of an array"
+      ]);
+    });
+
+    it("preserves warnings when deleting a list", async () => {
+      respondWith("delete", {
+        success: true,
+        _warnings: [
+          "There is a newer API version available, please consider upgrading to v2."
+        ]
+      });
+
+      const response = await geocoder.list.delete(42);
+
+      expect(response._warnings).toEqual([
+        "There is a newer API version available, please consider upgrading to v2."
+      ]);
+    });
+  });
+
+  describe("distance matrix job responses", () => {
+    it("preserves warnings when creating a job", async () => {
+      respondWith("post", {
+        identifier: "dmj_abc123",
+        status: "ENQUEUED",
+        _warnings: [
+          "There is a newer API version available, please consider upgrading to v2."
+        ]
+      });
+
+      const response = await geocoder.createDistanceMatrixJob(
+        "Store coverage",
+        [[38.886665, -77.094733]],
+        [[38.897675, -77.036547]]
+      );
+
+      expect(response._warnings).toEqual([
+        "There is a newer API version available, please consider upgrading to v2."
+      ]);
+    });
+
+    it("preserves warnings on job status", async () => {
+      respondWith("get", {
+        data: { identifier: "dmj_abc123", status: "COMPLETED" },
+        _warnings: [
+          "The fields parameter should contain a comma-separated list of fields instead of an array"
+        ]
+      });
+
+      const response = await geocoder.distanceMatrixJobStatus("dmj_abc123");
+
+      expect(response._warnings).toEqual([
+        "The fields parameter should contain a comma-separated list of fields instead of an array"
+      ]);
+    });
+
+    it("preserves warnings when listing jobs", async () => {
+      respondWith("get", {
+        data: [],
+        total: 0,
+        _warnings: [
+          "The fields parameter should contain a comma-separated list of fields instead of an array"
+        ]
+      });
+
+      const response = await geocoder.distanceMatrixJobs();
+
+      expect(response._warnings).toEqual([
+        "The fields parameter should contain a comma-separated list of fields instead of an array"
+      ]);
+    });
+
+    it("preserves warnings when deleting a job", async () => {
+      respondWith("delete", {
+        success: true,
+        _warnings: [
+          "There is a newer API version available, please consider upgrading to v2."
+        ]
+      });
+
+      const response = await geocoder.deleteDistanceMatrixJob("dmj_abc123");
+
+      expect(response._warnings).toEqual([
+        "There is a newer API version available, please consider upgrading to v2."
+      ]);
+    });
+  });
+
+  describe("error responses", () => {
+    it("exposes warnings attached to an error response", async () => {
+      expect.assertions(3);
+
+      rejectWith("get", 422, {
+        error: "Could not geocode address. Postal code or city required.",
+        _warnings: ["The field congress is not recognized. Did you mean cd?"]
+      });
+
+      try {
+        await geocoder.geocode("1109 N Highland St", ["congress"]);
+      } catch (err) {
+        expect(err.message).toEqual(
+          "Could not geocode address. Postal code or city required."
+        );
+        expect(err.code).toEqual(422);
+        expect(err.warnings).toEqual([
+          "The field congress is not recognized. Did you mean cd?"
+        ]);
+      }
+    });
+
+    it("reports no warnings when the error response carries none", async () => {
+      expect.assertions(1);
+
+      rejectWith("get", 403, { error: "Invalid API key" });
+
+      try {
+        await geocoder.geocode("1109 N Highland St, Arlington VA");
+      } catch (err) {
+        expect(err.warnings).toEqual([]);
+      }
+    });
+  });
+});

package/lib/index.d.ts

@@ -38,6 +38,17 @@ declare module 'geocodio-library-node' {
     toObject(): { lat: number; lng: number; id?: string };
   }
 
+  // Non-fatal advisories the API returns under the `_warnings` key, e.g. an
+  // unrecognized field name, a superseded API version, or a skipped append.
+  // The key is only present when at least one warning was raised.
+  export type Warnings = string[];
+
+  // Errors thrown for non-2xx API responses
+  export interface GeocodioError extends Error {
+    code: number;
+    warnings: Warnings;
+  }
+
   // Coordinate input types (accept multiple formats)
   export type CoordinateInput =
     | Coordinate
@@ -101,6 +112,7 @@ declare module 'geocodio-library-node' {
     origins_count: number;
     destinations_count: number;
     total_calculations: number;
+    _warnings?: Warnings;
   }
 
   export interface DistanceJobStatusResponse {
@@ -114,6 +126,7 @@ declare module 'geocodio-library-node' {
       total_calculations: number;
       calculations_completed: number;
     };
+    _warnings?: Warnings;
   }
 
   export interface DistanceJobsListResponse {
@@ -138,6 +151,7 @@ declare module 'geocodio-library-node' {
     prev_page_url: string | null;
     to: number;
     total: number;
+    _warnings?: Warnings;
   }
 
   export interface DistanceJobOptions extends DistanceOptions {
@@ -346,6 +360,15 @@ declare module 'geocodio-library-node' {
     exact_match: boolean;
   }
 
+  export interface UKLegislativeDistrict {
+    district_type: string;
+    gss_code: string;
+    ocd_id: string;
+    name: string;
+    is_upcoming_district: boolean;
+    source: string;
+  }
+
   export interface Fields {
     congressional_districts?: CongressionalDistrict[];
     state_legislative_districts?: StateLegislativeDistricts;
@@ -353,6 +376,9 @@ declare module 'geocodio-library-node' {
     timezone?: Timezone;
     census?: Census;
     zip4?: Zip4;
+    uk_westminster?: UKLegislativeDistrict[];
+    uk_devolved?: UKLegislativeDistrict[];
+    uk_local?: UKLegislativeDistrict[];
     [key: string]: unknown;
   }
 
@@ -364,6 +390,7 @@ declare module 'geocodio-library-node' {
     accuracy_type: GeocodeAccuracyType;
     source?: string;
     fields?: Fields;
+    _warnings?: Warnings;
   }
 
   export type FieldOption =
@@ -390,6 +417,12 @@ declare module 'geocodio-library-node' {
     | 'census2020'
     | 'provriding'
     | 'riding'
+    | 'uk-westminster'
+    | 'uk-westminster-next'
+    | 'uk-devolved'
+    | 'uk-devolved-next'
+    | 'uk-local'
+    | 'uk-local-next'
     | 'zip4'
     | 'acs-demographics'
     | 'acs-economics'
@@ -399,7 +432,7 @@ declare module 'geocodio-library-node' {
 
   export interface SingleGeocodeResponse {
     results: GeocodedAddress[];
-    _warnings?: string[];
+    _warnings?: Warnings;
   }
 
   export interface BatchGeocodeResponse<Q extends string | AddressInputComponents, T extends Array<Q> | Record<string, Q>> {
@@ -413,7 +446,7 @@ declare module 'geocodio-library-node' {
 
   export interface ReverseGeocodeResponse {
     results: GeocodedAddress[];
-    _warnings?: string[];
+    _warnings?: Warnings;
   }
 
   export interface BatchReverseGeocodeResponse<Q extends string | [number, number], T extends Array<Q> | Record<string, Q>> {
@@ -431,6 +464,24 @@ declare module 'geocodio-library-node' {
     file: {
       filename: string;
     };
+    _warnings?: Warnings;
+  }
+
+  export interface ListStatusResponse {
+    id: number;
+    _warnings?: Warnings;
+    [key: string]: unknown;
+  }
+
+  export interface ListsResponse {
+    data: unknown[];
+    _warnings?: Warnings;
+    [key: string]: unknown;
+  }
+
+  export interface DeleteResponse {
+    success: boolean;
+    _warnings?: Warnings;
   }
 
   export default class Geocodio {
@@ -490,16 +541,16 @@ declare module 'geocodio-library-node' {
 
     downloadDistanceMatrixJob(id: string | number, filePath: string): Promise<void>;
 
-    deleteDistanceMatrixJob(id: string | number): Promise<void>;
+    deleteDistanceMatrixJob(id: string | number): Promise<DeleteResponse>;
 
     // List API
     list: {
       create(filename: string, direction: string, format: string, callback: string): Promise<ListResponse>;
-      status(listId: number): Promise<unknown>;
-      all(): Promise<unknown>;
+      status(listId: number): Promise<ListStatusResponse>;
+      all(): Promise<ListsResponse>;
       download(listId: number, output: string): Promise<unknown>;
-      delete(listId: number): Promise<unknown>;
-      deleteList(listId: number): Promise<unknown>; // Alias for delete
+      delete(listId: number): Promise<DeleteResponse>;
+      deleteList(listId: number): Promise<DeleteResponse>; // Alias for delete
     };
   }
 }

package/lib/index.js

@@ -535,6 +535,9 @@ class Geocodio {
 
           const decoratedError = new Error(errorMessage);
           decoratedError.code = code;
+          // Warnings ride along on error responses too, e.g. a misspelled
+          // field name in a request that failed for an unrelated reason
+          decoratedError.warnings = this.extractWarnings(error.response.data);
 
           throw decoratedError;
         } else {
@@ -543,6 +546,14 @@ class Geocodio {
       });
   }
 
+  extractWarnings(data) {
+    if (data && Array.isArray(data._warnings)) {
+      return data._warnings;
+    }
+
+    return [];
+  }
+
   formatUrl(endpoint) {
     return `https://${this.hostname}/${this.apiVersion}/${endpoint}`;
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "geocodio-library-node",
-  "version": "2.0.0",
+  "version": "2.2.0",
   "description": "geocod.io geocoding API library",
   "homepage": "https://github.com/Geocodio/geocodio-library-node",
   "author": {