universal-parcel-scraper 0.49.0-main.543 → 0.49.0-main.548

package/NOTICE

@@ -14,3 +14,9 @@ Facility coordinates include OpenStreetMap data (https://www.openstreetmap.org/c
 licensed under the Open Database License. Natural Earth country label points
 (https://www.naturalearthdata.com) and OurAirports airports
 (https://ourairports.com/data/) are public domain.
+
+Indian PIN code towns (places/pincodes.json) are derived from: Department of
+Posts, Ministry of Communications, 2025, All India Pincode Directory till last
+month, Open Government Data Platform India, 26/06,
+https://www.data.gov.in/resource/all-india-pincode-directory-till-last-month.
+Published under Government Open Data License - India: https://www.data.gov.in/Godl.

package/README.md

@@ -149,7 +149,7 @@ createTracker({ providers: ['ParcelsApp', 'Ship24', '17TRACK', 'Postal Ninja', '
 <!-- GENERATED:stages -->
 <img src="docs/assets/stages.svg" alt="DHL: Die Sendung wurde in das Zustellfahrzeug geladen.; Mondial Relay: En cours de livraison; Correios Brazil: Objeto saiu para entrega ao destinatário; Correos Express: EN REPARTO; Yamato Transport: 配達中; La Poste / Colissimo: DISTOU. All are filed under out_for_delivery." width="760">
 
-The carrier folders record 2,751 such statuses, each filed under one stage.
+The carrier folders record 2,756 such statuses, each filed under one stage.
 <!-- /GENERATED:stages -->
 
 Wording nobody recorded yet goes through a classifier that reads seven European languages.

package/data/detection-golden.json

@@ -9404,7 +9404,7 @@
     ]
   },
   {
-    "input": "62162057330000611",
+    "input": "62100000000000000",
     "carrier": "unknown",
     "confidence": "low",
     "candidates": [

package/dist/carriers/aliexpress/adapter.js

@@ -170,6 +170,8 @@ export function parseCainiaoTrackingResponse(value, trackingNumber) {
             time: scanTime(event),
             location,
             description,
+            // The code keys the app's review of a scan the map does not stage.
+            ...(/^[A-Z0-9_]{1,64}$/.test(code) ? { provider_code: code } : {}),
             ...(mapped ? { stage: actionStage[mapped] ?? 'in_transit' } : {}),
         };
     });

package/dist/carriers/aliexpress/status.d.ts

@@ -16,6 +16,7 @@
  */
 import type { CarrierStatus } from '../../core/result/index.js';
 import type { Stage } from '../../core/status/index.js';
+import type { CarrierStatusMap } from '../../core/status/statusMap.js';
 /** Parcel-level order tokens, used only when the newest trace has no action code. */
 export declare const CAINIAO_STATUS: Map<string, CarrierStatus>;
 export declare const CAINIAO_ACTION_STATUS: Map<string, CarrierStatus>;
@@ -29,3 +30,9 @@ export declare function cainiaoActionCode(value: unknown): string;
  * the shipment and to every historical event, exactly as before the move.
  */
 export declare function cainiaoStageByStatus(latestActionCode: string): Partial<Record<CarrierStatus, Stage>>;
+/**
+ * What the map says about one scan, by its action code. An out-for-delivery
+ * code reads as the van or a pickup point by the newest code of the whole
+ * reply, so the code alone does not answer it.
+ */
+export declare const statusMap: CarrierStatusMap;

package/dist/carriers/aliexpress/status.js

@@ -12,6 +12,9 @@ export const CAINIAO_STATUS = new Map([
 // leg). The parcel-level `status` token vocabulary is unestablished (real
 // parcels carry DELIVERED/CLEAR_CUSTOMS/transport/pickup/delivered), so the
 // newest latestTrace.actionCode wins and the token is only a fallback.
+// LH_HO_OUT_SUCCESS, TD_TRANSWH_OUTBOUND, TD_TRANS_ARRIVE_DCP and
+// GTMS_SC_DEPART were seen live on 2026-10-08, between the linehaul's arrival
+// and the local partner's round, each worded as one more leg of the journey.
 export const CAINIAO_ACTION_STATUS = new Map([
     ['GWMS_ACCEPT', 'pending'],
     ['GWMS_PACKAGE', 'pending'],
@@ -32,12 +35,15 @@ export const CAINIAO_ACTION_STATUS = new Map([
     ['LH_HO_AIRLINE', 'in_transit'],
     ['LH_DEPART', 'in_transit'],
     ['LH_ARRIVE', 'in_transit'],
+    ['LH_HO_OUT_SUCCESS', 'in_transit'],
     ['LH_POST_COLLECTION', 'in_transit'],
     ['COMMON_INTRANSIT', 'in_transit'],
     ['TD_TRANS_DEPART', 'in_transit'],
     ['TD_TRANS_ARRIVE', 'in_transit'],
     ['TD_TRANS_DEPART_C', 'in_transit'],
     ['TD_TRANS_ARRIVE_C', 'in_transit'],
+    ['TD_TRANSWH_OUTBOUND', 'in_transit'],
+    ['TD_TRANS_ARRIVE_DCP', 'in_transit'],
     ['CC_HO_IN_SUCCESS', 'in_transit'],
     ['CC_IM_START', 'in_transit'],
     ['CC_IM_SUCCESS', 'in_transit'],
@@ -45,6 +51,7 @@ export const CAINIAO_ACTION_STATUS = new Map([
     ['CC_IM_FAILURE', 'exception'],
     ['CC_IM_EXCEPTION', 'exception'],
     ['GTMS_ACCEPT', 'in_transit'],
+    ['GTMS_SC_DEPART', 'in_transit'],
     ['SC_ARRIVE', 'in_transit'],
     ['SC_DEPART', 'in_transit'],
     ['OE_DEPART', 'in_transit'],
@@ -77,3 +84,29 @@ export function cainiaoStageByStatus(latestActionCode) {
         exception: 'exception',
     };
 }
+/**
+ * The scans the review queue holds without their action code, from before
+ * events kept it, by `normalizeStatusWording` wording without the town
+ * bracket. Each is the standard wording Cainiao gives that code.
+ */
+const UNCODED_SCANS = new Map([
+    ['handed over from linehaul office', 'LH_HO_OUT_SUCCESS'],
+    ['leaving transit country/region', 'TD_TRANSWH_OUTBOUND'],
+    ['awaiting for transit to final delivery office', 'TD_TRANS_ARRIVE_DCP'],
+    ['departed from destination country/region sorting center', 'GTMS_SC_DEPART'],
+]);
+/**
+ * What the map says about one scan, by its action code. An out-for-delivery
+ * code reads as the van or a pickup point by the newest code of the whole
+ * reply, so the code alone does not answer it.
+ */
+export const statusMap = {
+    stage: (code, wording) => {
+        const action = code ? cainiaoActionCode(code) : UNCODED_SCANS.get(wording.replace(/^\[[^\]]*\]\s*/, ''));
+        const status = action ? CAINIAO_ACTION_STATUS.get(action) : undefined;
+        if (!status || status === 'out_for_delivery')
+            return undefined;
+        return cainiaoStageByStatus('')[status] ?? 'in_transit';
+    },
+    gaps: [],
+};

package/dist/carriers/aliexpress/statuses.json

@@ -183,6 +183,15 @@
       "firstSeen": "2026-09-12",
       "note": ""
     },
+    {
+      "code": "LH_HO_OUT_SUCCESS",
+      "wording": "Handed over from linehaul office",
+      "language": "en",
+      "stage": "in_transit",
+      "confirmedBy": "live",
+      "firstSeen": "2026-10-08",
+      "note": "Seen live after the linehaul office arrival, before the transit country scans."
+    },
     {
       "code": "LH_POST_COLLECTION",
       "stage": "in_transit",
@@ -225,6 +234,24 @@
       "firstSeen": "2026-09-12",
       "note": ""
     },
+    {
+      "code": "TD_TRANSWH_OUTBOUND",
+      "wording": "Leaving transit country/region",
+      "language": "en",
+      "stage": "in_transit",
+      "confirmedBy": "live",
+      "firstSeen": "2026-10-08",
+      "note": "Seen live between the arrival in and the departure from the transit country."
+    },
+    {
+      "code": "TD_TRANS_ARRIVE_DCP",
+      "wording": "Awaiting for transit to final delivery office",
+      "language": "en",
+      "stage": "in_transit",
+      "confirmedBy": "live",
+      "firstSeen": "2026-10-08",
+      "note": "Seen live after customs or the transit country, before the local partner received the parcel."
+    },
     {
       "code": "CC_HO_IN_SUCCESS",
       "stage": "in_transit",
@@ -274,6 +301,15 @@
       "firstSeen": "2026-09-12",
       "note": ""
     },
+    {
+      "code": "GTMS_SC_DEPART",
+      "wording": "Departed from destination country/region sorting center",
+      "language": "en",
+      "stage": "in_transit",
+      "confirmedBy": "live",
+      "firstSeen": "2026-10-08",
+      "note": "Seen live between the local partner receiving the parcel and its round."
+    },
     {
       "code": "SC_ARRIVE",
       "stage": "in_transit",

package/dist/carriers/correos-spain/adapter.js

@@ -122,6 +122,8 @@ export function parseCorreosSpainTrackingResponse(payload, trackingNumber, exped
                 time: time.iso,
                 location: '',
                 description,
+                // The code keys the app's review of a scan the map does not stage.
+                ...(/^[A-Z0-9.]{1,32}$/.test(code) ? { provider_code: code } : {}),
                 ...(classified ? { stage: classified.stage } : {}),
             },
             classified,

package/dist/carriers/correos-spain/status.d.ts

@@ -13,5 +13,8 @@
  * out for delivery → failed attempt → office hold → collected).
  */
 import type { ClassifiedStatus } from '../../core/status/index.js';
+import type { CarrierStatusMap } from '../../core/status/statusMap.js';
 /** The stage and status for a Correos `codEvento`, or undefined when unmapped. */
 export declare function classifyCorreosSpainStatus(code: string): ClassifiedStatus | undefined;
+/** What the map says about one scan, by its `codEvento`. */
+export declare const statusMap: CarrierStatusMap;

package/dist/carriers/correos-spain/status.js

@@ -63,3 +63,19 @@ const EVENT_STATUS = {
 export function classifyCorreosSpainStatus(code) {
     return EVENT_STATUS[code];
 }
+/**
+ * The scans the review queue holds without their code, from before events
+ * kept it, by `normalizeStatusWording` wording. Each is the summary Correos
+ * gives that code.
+ */
+const UNCODED_SCANS = new Map([
+    ['a disposición del destinatario', 'G01L020V'],
+]);
+/** What the map says about one scan, by its `codEvento`. */
+export const statusMap = {
+    stage: (code, wording) => {
+        const key = code ? code.toLocaleUpperCase('en-US') : UNCODED_SCANS.get(wording);
+        return key ? classifyCorreosSpainStatus(key)?.stage : undefined;
+    },
+    gaps: [],
+};

package/dist/carriers/dpd/status.js

@@ -121,5 +121,6 @@ export const statusMap = {
         { code: 'SPE', note: 'A delivery estimate or a changed delivery day, not a scan.' },
         { code: 'MSDLO', note: 'The notice DPD emailed for the delivery round, not a scan.' },
         { code: 'MIDLI', note: "The recipient's delivery instruction, not a scan." },
+        { code: 'ENA', note: "A data exchange inside DPD's systems, not a scan: it comes before the parcel reaches the origin depot." },
     ],
 };

package/dist/carriers/dpd/statuses.json

@@ -207,6 +207,14 @@
       "confirmedBy": "live",
       "firstSeen": "2026-10-05",
       "note": "The recipient's delivery instruction, not a scan."
+    },
+    {
+      "code": "ENA",
+      "wording": "We are exchanging data internally",
+      "language": "en",
+      "confirmedBy": "live",
+      "firstSeen": "2026-10-02",
+      "note": "A data exchange inside DPD's systems, not a scan; seen twice before the parcel reached the origin depot."
     }
   ]
 }

package/dist/carriers/dpd-fr/status.d.ts

@@ -16,6 +16,7 @@
  * pages kept by the Internet Archive.
  */
 import type { ClassifiedStatus } from '../../core/status/index.js';
+import type { CarrierStatusMap } from '../../core/status/statusMap.js';
 /**
  * Lowercase, accent-free, punctuation-free form used for every wording
  * comparison. A spacing accent typed for an apostrophe ("l´expéditeur")
@@ -24,3 +25,9 @@ import type { ClassifiedStatus } from '../../core/status/index.js';
 export declare function comparableText(value: string): string;
 export declare function includesAny(value: string, phrases: string[]): boolean;
 export declare function classifyStatus(description: string): ClassifiedStatus;
+/**
+ * What the map says about one scan. The trace page has no codes, so the
+ * wording is the whole key, and wording the map does not recognize gets no
+ * stage, as in the adapter.
+ */
+export declare const statusMap: CarrierStatusMap;

package/dist/carriers/dpd-fr/status.js

@@ -1,4 +1,4 @@
-import { clean } from '../../core/transport/index.js';
+import { clean } from '../../core/transport/text.js';
 /**
  * Lowercase, accent-free, punctuation-free form used for every wording
  * comparison. A spacing accent typed for an apostrophe ("l´expéditeur")
@@ -106,3 +106,15 @@ export function classifyStatus(description) {
     // package's "omit the stage when it is not mapped" rule; the adapter drops it.
     return { status: 'unknown', stage: 'in_transit' };
 }
+/**
+ * What the map says about one scan. The trace page has no codes, so the
+ * wording is the whole key, and wording the map does not recognize gets no
+ * stage, as in the adapter.
+ */
+export const statusMap = {
+    stage: (code, wording) => {
+        const classified = code ? null : classifyStatus(wording);
+        return classified && classified.status !== 'unknown' ? classified.stage : undefined;
+    },
+    gaps: [],
+};

package/dist/carriers/hermes/numbers.json

@@ -2,7 +2,7 @@
   "carrier": "hermes",
   "records": [
     {
-      "number": "62162057330000611",
+      "number": "62100000000000000",
       "role": "shipment",
       "evidence": "synthetic",
       "derivedFrom": "official_shape",
@@ -14,7 +14,7 @@
           "dhl-ecommerce"
         ]
       },
-      "note": "Made-up number that follows the published format. Filed under Hermes Einrichtungs-Service, which no rule claims."
+      "note": "Made-up number in the 17-digit parcel-number shape. Hermes rejects it, so it opens no order. Filed under Hermes Einrichtungs-Service, which no rule claims."
     }
   ]
 }

package/dist/carriers/ups/adapter.js

@@ -9,7 +9,7 @@ import { NOOP_RECORDER } from '../../core/telemetry/index.js';
 import { calendarDay } from '../../core/time/index.js';
 import { clean, cleanScalar, decodeText, fetchBounded, parseJsonBytes, TRAWL_TRANSPORT_ALLOWANCE_MS, TrawlClient } from '../../core/transport/index.js';
 import { isRecord } from '../../core/types.js';
-import { UPS_PROGRESS_STATUS, upsActivityStage, upsStatus } from './status.js';
+import { UPS_PROGRESS_STATUS, upsActivityStage, upsBannerStage, upsStatus } from './status.js';
 const TRACKING_BASE = 'https://www.ups.com/track';
 const STATUS_API = 'https://webapis.ups.com/track/api/Track/GetStatus?loc=en_US';
 const TRAWL_PROVIDER = 'TRAWL while fetching UPS';
@@ -180,9 +180,10 @@ export function parseUPSTrackingHtml(page, trackingNumber) {
     // town, not where the parcel is, so it never becomes the banner's place.
     const location = clean($('#stApp_deliveredToAddress').last().text());
     // The banner has no clock, so its event carries none.
+    const bannerStage = upsBannerStage(statusText);
     const events = currentStatus === 'unknown'
         ? []
-        : [{ ...(location ? { location } : {}), description: statusText }];
+        : [{ ...(location ? { location } : {}), description: statusText, ...(bannerStage ? { stage: bannerStage } : {}) }];
     return {
         status: currentStatus,
         last_status_text: statusText,

package/dist/carriers/ups/status.d.ts

@@ -13,7 +13,7 @@
  */
 import type { CarrierStatus } from '../../core/result/index.js';
 import type { Stage } from '../../core/status/index.js';
-import type { CarrierStatusMap } from '../../core/status/statusMap.js';
+import { type CarrierStatusMap } from '../../core/status/statusMap.js';
 /**
  * Classify UPS status prose. `hasEvents` reports that the shipment already has
  * a scan history, which is what makes unrecognized wording "moving" rather
@@ -27,5 +27,7 @@ export declare function upsStatus(text: string, hasEvents?: boolean): CarrierSta
 export declare const UPS_PROGRESS_STATUS: Readonly<Record<string, CarrierStatus>>;
 /** The stage a scan's `actCode` stands for, or undefined when the code is not mapped. */
 export declare function upsActivityStage(code: string): Stage | undefined;
-/** What the map says about one scan, by its activity code. */
+/** The stage of the rendered page's banner, or undefined for a milestone it does not name. */
+export declare function upsBannerStage(text: string): Stage | undefined;
+/** What the map says about one scan: by its activity code, or as the banner without one. */
 export declare const statusMap: CarrierStatusMap;

package/dist/carriers/ups/status.js

@@ -1,3 +1,4 @@
+import { normalizeStatusWording } from '../../core/status/statusMap.js';
 const EXCEPTION_TERMS = [
     'return to sender', 'returned', 'delivery attempted', 'we missed you',
     'not delivered', 'exception', 'action required',
@@ -76,8 +77,23 @@ const ACTIVITY_STAGES = new Map([
 export function upsActivityStage(code) {
     return ACTIVITY_STAGES.get(code.trim().toUpperCase());
 }
-/** What the map says about one scan, by its activity code. */
+/**
+ * The milestone the rendered page's banner names, the only wording the
+ * adapter reads without an activity code. Scan wording without its code is
+ * not read: "Arrived at Facility" is both the origin scan and an arrival.
+ */
+const BANNER_STAGES = new Map([
+    ['label created', 'registered'],
+    ['on the way', 'in_transit'],
+    ['out for delivery', 'out_for_delivery'],
+    ['delivered', 'delivered'],
+]);
+/** The stage of the rendered page's banner, or undefined for a milestone it does not name. */
+export function upsBannerStage(text) {
+    return BANNER_STAGES.get(normalizeStatusWording(text));
+}
+/** What the map says about one scan: by its activity code, or as the banner without one. */
 export const statusMap = {
-    stage: (code) => (code ? upsActivityStage(code) : undefined),
+    stage: (code, wording) => (code ? upsActivityStage(code) : upsBannerStage(wording)),
     gaps: [],
 };

package/dist/carriers/ups/statuses.json

@@ -49,17 +49,17 @@
     { "wording": "Not Delivered", "language": "en", "stage": "failed_attempt", "confirmedBy": "prior-art", "firstSeen": "2026-09-12", "note": "Adapter result status: exception." },
     { "wording": "Exception", "language": "en", "stage": "failed_attempt", "confirmedBy": "prior-art", "firstSeen": "2026-09-12", "note": "Adapter result status: exception." },
     { "wording": "Action Required", "language": "en", "stage": "failed_attempt", "confirmedBy": "prior-art", "firstSeen": "2026-09-12", "note": "Adapter result status: exception." },
-    { "wording": "Delivered", "language": "en", "stage": "delivered", "confirmedBy": "prior-art", "firstSeen": "2026-09-12", "note": "" },
+    { "wording": "Delivered", "language": "en", "stage": "delivered", "confirmedBy": "prior-art", "firstSeen": "2026-09-12", "note": "As the rendered page's banner, which has no code, it gets this stage from the map." },
     { "wording": "Left at", "language": "en", "stage": "delivered", "confirmedBy": "prior-art", "firstSeen": "2026-09-12", "note": "Prefix of UPS's \"Left at: Front Door\" wording; the location detail itself is never retained." },
-    { "wording": "Out For Delivery", "language": "en", "stage": "out_for_delivery", "confirmedBy": "fixture", "firstSeen": "2026-09-12", "note": "Seen as \"Out For Delivery Today\" in fixtures/out-for-delivery.json." },
-    { "wording": "On the Way", "language": "en", "stage": "in_transit", "confirmedBy": "prior-art", "firstSeen": "2026-09-12", "note": "" },
+    { "wording": "Out For Delivery", "language": "en", "stage": "out_for_delivery", "confirmedBy": "fixture", "firstSeen": "2026-09-12", "note": "Seen as \"Out For Delivery Today\" in fixtures/out-for-delivery.json. As the rendered page's banner, which has no code, it gets this stage from the map." },
+    { "wording": "On the Way", "language": "en", "stage": "in_transit", "confirmedBy": "prior-art", "firstSeen": "2026-09-12", "note": "As the rendered page's banner, which has no code, it gets this stage from the map." },
     { "wording": "In Transit", "language": "en", "stage": "in_transit", "confirmedBy": "prior-art", "firstSeen": "2026-09-12", "note": "" },
     { "wording": "We Have Your Package", "language": "en", "stage": "in_transit", "confirmedBy": "prior-art", "firstSeen": "2026-09-12", "note": "" },
     { "wording": "First UPS Possession", "language": "en", "stage": "accepted", "confirmedBy": "prior-art", "firstSeen": "2026-09-12", "note": "Adapter result status: in_transit." },
     { "wording": "Departed", "language": "en", "stage": "in_transit", "confirmedBy": "fixture", "firstSeen": "2026-09-12", "note": "Seen as \"Departed from Facility\"." },
     { "wording": "Arrived", "language": "en", "stage": "in_transit", "confirmedBy": "fixture", "firstSeen": "2026-09-12", "note": "Seen as \"Arrived at Facility\"." },
     { "wording": "Processing at UPS Facility", "language": "en", "stage": "in_transit", "confirmedBy": "prior-art", "firstSeen": "2026-09-12", "note": "" },
-    { "wording": "Label Created", "language": "en", "stage": "pending", "confirmedBy": "prior-art", "firstSeen": "2026-09-12", "note": "" },
+    { "wording": "Label Created", "language": "en", "stage": "registered", "confirmedBy": "prior-art", "firstSeen": "2026-09-12", "note": "The prose reads it as status pending. As the rendered page's banner, which has no code, it gets this stage from the map." },
     { "wording": "Manifest Upload", "language": "en", "stage": "pending", "confirmedBy": "prior-art", "firstSeen": "2026-09-12", "note": "" },
     { "wording": "Shipment Ready for UPS", "language": "en", "stage": "pending", "confirmedBy": "prior-art", "firstSeen": "2026-09-12", "note": "" },
     { "wording": "Delivered to UPS Access Point™ location and awaiting customer pickup.", "language": "en", "stage": "ready_for_pickup", "confirmedBy": "prior-art", "firstSeen": "2026-09-20", "note": "Checked before the delivered wording, which the sentence also contains." }

package/dist/core/catalog/statusMaps.js

@@ -8,10 +8,13 @@
  * `statusMap` next to its map in `status.ts`; carriers without one answer
  * `unknown`.
  */
+import { statusMap as aliexpress } from '../../carriers/aliexpress/status.js';
 import { statusMap as chronopost } from '../../carriers/chronopost/status.js';
+import { statusMap as correosSpain } from '../../carriers/correos-spain/status.js';
 import { statusMap as dhlExpress } from '../../carriers/dhl-express/status.js';
 import { statusMap as dpd } from '../../carriers/dpd/status.js';
 import { statusMap as dpdDe } from '../../carriers/dpd-de/status.js';
+import { statusMap as dpdFr } from '../../carriers/dpd-fr/status.js';
 import { statusMap as laPoste } from '../../carriers/la-poste/status.js';
 import { statusMap as postlogistics } from '../../carriers/postlogistics/status.js';
 import { statusMap as swissPost } from '../../carriers/swiss-post/status.js';
@@ -22,8 +25,8 @@ import { normalizeStatusWording } from '../status/statusMap.js';
 import { CARRIER_DEFINITIONS } from './definitions.js';
 /** By adapter: a carrier served by another's adapter, as Delivengo by La Poste's, reads that map. */
 export const STATUS_MAPS = {
-    chronopost, 'dhl-express': dhlExpress, dpd, 'dpd-de': dpdDe, 'la-poste': laPoste, postlogistics, 'swiss-post': swissPost, tnt, ups,
-    yunexpress,
+    aliexpress, chronopost, 'correos-spain': correosSpain, 'dhl-express': dhlExpress, dpd, 'dpd-de': dpdDe, 'dpd-fr': dpdFr,
+    'la-poste': laPoste, postlogistics, 'swiss-post': swissPost, tnt, ups, yunexpress,
 };
 const UNKNOWN = { kind: 'unknown' };
 function carrierStatusMap(carrier) {

package/dist/places/hubs.json

@@ -1,5 +1,6 @@
 [
   { "country": "FR", "names": ["Roissy"], "town": "Roissy-en-France", "airport": "CDG" },
   { "country": "GB", "names": ["Heathrow"], "town": "London", "airport": "LHR" },
-  { "country": "GB", "names": ["East Midlands"], "town": "Castle Donington", "airport": "EMA" }
+  { "country": "GB", "names": ["East Midlands"], "town": "Castle Donington", "airport": "EMA" },
+  { "country": "PL", "names": ["Sękocin Stary"], "town": "Sękocin Stary", "latitude": 52.108, "longitude": 20.88, "source": "https://download.geonames.org/export/zip/PL.zip" }
 ]

package/dist/places/index.js

@@ -5,6 +5,7 @@ import facilityList from './facilities.json' with { type: 'json' };
 import hubList from './hubs.json' with { type: 'json' };
 import { nameKey, nameKeys } from './names.mjs';
 const DATA = new URL('./places.tsv.br', import.meta.url);
+const PINCODES = new URL('./pincodes.json', import.meta.url);
 // Words for facilities and services rather than places ("Agence DPD de La Crau", "PAKETZENTRUM", "ISC NEW YORK NY(USPS)").
 const FACILITY_WORDS = new Set(`
   agence agency air airport area branch bureau cedex cidex center centre centro centrum clasificacion colis
@@ -53,9 +54,11 @@ const HUB_THOUSANDS = 50;
 const NAMESAKE_THOUSANDS = 100;
 // Swiss Post scans end in the site's six-digit number: "Zürich Briefzentrum 801050".
 const FACILITIES = new Map(facilityList.map((facility) => [`${facility.country}:${facility.code}`, facility]));
-// Names carriers give a hub instead of its town: "ROISSY" is Paris-Charles de Gaulle, not Roissy-en-Brie.
+// Names carriers give a hub instead of its town ("ROISSY" is Paris-Charles de Gaulle, not
+// Roissy-en-Brie), and hubs in villages the gazetteer is too coarse for ("SEKOCIN STARY").
 const HUBS = new Map(hubList.flatMap((hub) => hub.names.map((name) => [nameKey(name), hub])));
 let loaded = null;
+let pincodes = null;
 function gazetteer() {
     if (loaded)
         return loaded;
@@ -225,14 +228,16 @@ function cjkPhrases(field) {
     }
     return found;
 }
-/** The places a phrase can name. A hub's nickname replaces the towns of its country that share it. */
+/** The places a phrase can name. A hub's name replaces the towns of its country that share it. */
 function candidates(data, key) {
     const hub = HUBS.get(key);
-    const airport = hub && data.airports.get(hub.airport);
+    // At its airport, or at its own point when its village is too small for the gazetteer.
+    const airport = hub?.airport ? data.airports.get(hub.airport) : undefined;
+    const point = airport ?? (hub?.latitude !== undefined && hub.longitude !== undefined ? { latitude: hub.latitude, longitude: hub.longitude } : undefined);
     const towns = [data.keys.get(key) ?? []].flat().flatMap((entry) => {
         const index = entry < 0 ? ~entry : entry;
         const country = data.codes[data.country[index]];
-        if (airport && country === hub.country)
+        if (point && country === hub.country)
             return [];
         return [{
                 country, admin1: data.codes[data.admin1[index]] ?? '', admin2: data.codes[data.admin2[index]] ?? '',
@@ -240,11 +245,11 @@ function candidates(data, key) {
                 alternate: entry < 0, name: data.names[index],
             }];
     });
-    if (!airport)
+    if (!hub || !point)
         return towns;
     return [...towns, {
-            country: hub.country, admin1: '', admin2: '', latitude: airport.latitude, longitude: airport.longitude,
-            thousands: HUB_THOUSANDS, alternate: false, name: hub.town, site: airport.name, hub: true,
+            country: hub.country, admin1: '', admin2: '', latitude: point.latitude, longitude: point.longitude,
+            thousands: HUB_THOUSANDS, alternate: false, name: hub.town, ...(airport ? { site: airport.name } : {}), hub: true,
         }];
 }
 /**
@@ -316,6 +321,8 @@ export function locatePlace(location, hints = {}) {
     const outer = regions.filter((region) => !regions.some((other) => other.field === region.field
         && other.start < region.end && other.end > region.start && other.end - other.start > region.end - region.start));
     let best = null;
+    // Whether the text names a town at all, even one nothing confirms.
+    let namesTown = false;
     for (const [fieldIndex, list] of fieldPhrases.entries()) {
         for (const phrase of list) {
             const own = data.regions.get(phrase.key) ?? [];
@@ -330,7 +337,9 @@ export function locatePlace(location, hints = {}) {
             // ("Santa Catarina" on a Brazilian parcel).
             const named = phrase.whole ? own.filter((region) => (!country || region.country === country)
                 && (fieldIndex > 0 || region.country === country || hinted.includes(region.country))) : [];
-            for (const place of candidates(data, phrase.key)) {
+            const towns = candidates(data, phrase.key);
+            namesTown ||= towns.length > 0;
+            for (const place of towns) {
                 // A town may still be named like the region it lies in: Moscow in "…, Moscow",
                 // Sofia in its own "Sofia-Capital" rather than the province of Sofia around it.
                 const namesRegion = ` ${(data.regionNames.get(`${place.country}.${place.admin1}`) ?? []).join(' , ')} `.includes(` ${phrase.key} `);
@@ -380,6 +389,13 @@ export function locatePlace(location, hints = {}) {
             ...(place.site ? { site: place.site } : airport ? { site: airport.name } : {}),
         };
     }
+    // India Post ends an office's name with its PIN code, and abbreviates some names
+    // past reading ("KOL AP TMO 700052"): the PIN's town places a scan that names no
+    // town, when the scan or the parcel is in India. A town nothing confirmed is no
+    // abbreviation, and its six digits may be a Swiss Post site ("Daillens … 131070").
+    const pin = !namesTown && (country === 'IN' || (!country && hinted.includes('IN'))) ? pinPlace(data, rest) : null;
+    if (pin)
+        return pin;
     // A region alone places its country: "Guangdong Province", or "Santa Catarina"
     // on a Brazilian parcel, though Cape Verde has one too.
     if (!country) {
@@ -423,6 +439,40 @@ function airportFor(data, text, field, town, written, country) {
     return serving.length === 1 ? serving[0] : null;
 }
 const round = (value) => Math.round(value * 1000) / 1000;
+/**
+ * The town of the Indian PIN code a scan ends with. A foreign airport's code, alone or
+ * after its country's, names an office of exchange abroad ("Office - FRA 400051",
+ * "Office - DEFRA …"): the PIN is then the Indian office's, not where the scan happened.
+ */
+function pinPlace(data, text) {
+    const pin = /(?:^|\s)([1-8]\d{5})$/.exec(text)?.[1];
+    // Russian, Chinese and other six-digit postcodes come with their own script.
+    if (!pin || /[^\x20-\x7e]/.test(text))
+        return null;
+    for (const [, prefix, code] of text.matchAll(/\b([A-Z]{2})?([A-Z]{3})\b/g)) {
+        const airport = FACILITY_WORDS.has(code.toLowerCase()) ? undefined : data.airports.get(code);
+        if (airport && airport.country !== 'IN' && (!prefix || prefix === airport.country))
+            return null;
+    }
+    pincodes ??= JSON.parse(readFileSync(PINCODES, 'utf8'));
+    const { ranges, towns } = pincodes;
+    const value = Number(pin);
+    let low = 0;
+    let high = ranges.length - 1;
+    while (low <= high) {
+        const middle = (low + high) >> 1;
+        const [first, last, town] = ranges[middle];
+        if (value < first)
+            high = middle - 1;
+        else if (value > last)
+            low = middle + 1;
+        else {
+            const [name, latitude, longitude] = towns[town];
+            return { latitude, longitude, precision: 'city', country: 'IN', name };
+        }
+    }
+    return null;
+}
 /** A sorting centre the table knows, by its number and the town its name starts with. */
 function facilityPlace(text) {
     const match = /^(.*\S)\s+(\d{6})$/.exec(text);