@parseapi/sdk 1.10.5 → 1.11.0

package/README.md

@@ -273,7 +273,7 @@ const place = await parse.postal('28202', { country: 'US', deep: true });
 const propertyTax = place.deep?.property_tax;
 ```
 
-Read `population_period` alongside `population`: a reporting year (`YYYY`) or period (`YYYY-YYYY`), null when unknown or unverifiable. Keep missing or null values unknown and preserve a known zero. These fields belong to full place profiles. State district lists include each district's population and period. Postal nearby and distance detail remains metropolitan associations only. Continent population stays in core; Continent has no `population_period` field.
+Read `population` as the source’s count for that place boundary. Keep missing or null values unknown and preserve a known zero. State district lists include each district’s population. Postal nearby and distance detail remains metropolitan associations only. Continent population stays in core.
 
 Point returns the timezone ID with the core location. Its optional deep detail adds terrain and compact nearest-city context on every plan. A nearest city is null when none is within 200 km.
 
@@ -285,7 +285,7 @@ await parse.weather(40.7128, -74.006, { deep: true, date: '2026-08-15' });
 
 Tariff starts with the general schedule line. Paid deep adds units and the special and other schedule columns. An optional origin then resolves country-specific measures. The three calls below show those successive choices. Without origin, schedule detail is still returned and origin-dependent fields are null. A null effective rate is not a zero rate.
 
-Tariff lookup and search accept an optional `edition` fingerprint and `date` (`YYYY-MM-DD`). The edition pins exact immutable source bytes. A date is accepted only when verified source coverage exists. An edition without a date returns undated schedule context (`date: null`). Default requests use today. Paid detail exposes an open-string `reason` when `effective_rate` is null, including `incomplete_coverage`. A null rate never means zero. Explicit selections fail with `tariff_selection_mismatch` if an older server ignores the requested scope.
+Tariff lookup and search accept the `edition` ID returned by Tariff, such as `ted_3`, and an optional `date` (`YYYY-MM-DD`). The edition pins exact immutable source bytes. A date is accepted only when verified source coverage exists. An edition without a date returns undated schedule context (`date: null`). Default requests use today. Paid detail exposes an open-string `reason` when `effective_rate` is null, including `incomplete_coverage`. A null rate never means zero. Explicit selections fail with `tariff_selection_mismatch` if an older server ignores the requested scope.
 
 Origin means where the goods originate, not where they ship from. The effective rate covers matched stored schedule measures only. It is not complete duty or landed cost.
 
@@ -485,3 +485,37 @@ A device's emoji font remains the ordinary display.
 
 These additions are a local release candidate until the matching SDK and
 backend are published. Existing lookup and search contracts are preserved.
+
+
+## Canonical City operations
+
+Classic lookup, search, nearest and named-nearby methods retain their default envelopes and required-field models. Browse and coordinate-nearby use canonical lists: `object`, `data` and nullable `next_cursor` (camelCase properties in Swift/Kotlin). Keep all query options unchanged when continuing a page; no client fetches pages automatically.
+
+```js
+const page = await parse.city.search('Viena', {
+  format: 'list', match: 'fuzzy', maxDistance: 1,
+});
+```
+
+Select `format=resource` for one City or `format=list` for a collection. Country inclusion/exclusion sets, timezone sets, inclusive population and meter-elevation bounds, stored-center `bbox` and signed multi-key sorting are available for collections. Unknown numeric facts do not match range filters.
+
+Search defaults to prefix matching. Exact and fuzzy matching are explicit; fuzzy accepts maximum edit distance 1 or 2 and returns `match` evidence (`type`, `source`, `value`, `language`, `edit_distance`). Review a fuzzy choice before storing its ID.
+
+Reviewed children, ancestors and siblings use canonical lists with partial relationship coverage. Empty data does not prove there are no geographic relatives. Children/siblings accept page controls; ancestors do not. Distance reports great-circle kilometers and miles between stored centers: zero is known zero, null is unknown, and it does not imply travel time or containment.
+
+Strict `ambiguity=error` can return HTTP 409 `ambiguous_city` with up to two safe candidate identities. The existing error constructor and unrelated error metadata are preserved; candidates are retained only for that status/code and never contain Deep. GeoJSON is available through HTTP; these typed City list methods do not return GeoJSON.
+
+
+
+Reviewed name forms:
+
+```js
+const city = await parse.city.id('city_7aj899nvwyku', { format: 'resource', romanized: true });
+```
+
+Coverage by country and available fields is described at https://parseapi.com/city#coverage.
+
+`romanized=true` requests reviewed official name forms as `name_romanized` and `romanization_language` (camelCase in Swift/Kotlin). Current reviewed forms cover 20 Japanese whole-city aliases in ja-Latn. Missing or conflicting forms stay null; ASCII folding is not substituted for an official form.
+
+
+Conditional `If-None-Match` reads and GeoJSON currently use HTTP directly. A matching City ETag returns 304 without a body; ordinary billing and rate limits apply. These JSON client methods do not supply conditional-cache handling.

package/dist/index.cjs

@@ -285,7 +285,7 @@ var EmojiCatalog = class {
 };
 
 // src/index.ts
-var VERSION = "1.10.5";
+var VERSION = "1.11.0";
 var API_VERSION = "2.0.0";
 var DEFAULT_BASE_URL = "https://api.parseapi.com";
 var DEFAULT_TIMEOUT_MS = 1e4;
@@ -313,8 +313,11 @@ var ParseAPIError = class extends Error {
     this.retryAfter = retryAfter;
   }
 };
+function tariffEditionId(value) {
+  return typeof value === "string" && (value.length === 64 && /^[a-f0-9]{64}$/.test(value) || /^ted_[1-9][0-9]{0,19}(?![\s\S])/.test(value) && (value.length < 24 || value.slice(4) <= "18446744073709551615"));
+}
 function tariffSelection(result, opts) {
-  if ((opts?.edition !== void 0 || opts?.date !== void 0) && (typeof result.edition !== "string" || result.edition.length !== 64 || !/^[a-f0-9]{64}$/.test(result.edition) || opts.edition !== void 0 && result.edition !== opts.edition || (opts.date !== void 0 ? result.date !== opts.date : result.date != null))) {
+  if ((opts?.edition !== void 0 || opts?.date !== void 0) && (!tariffEditionId(result.edition) || opts.edition !== void 0 && result.edition !== opts.edition || (opts.date !== void 0 ? result.date !== opts.date : result.date != null))) {
     throw new ParseAPIError(0, "tariff_selection_mismatch", "Tariff response did not confirm the requested edition/date. The server may not support this selection.", null, null);
   }
   return result;
@@ -441,7 +444,7 @@ function parseAPI(apiKey, options = {}) {
             controller.signal.throwIfAborted();
           }
           signal?.throwIfAborted();
-          throw new ParseAPIError(
+          const error = new ParseAPIError(
             res.status,
             typeof body2.code === "string" ? body2.code : "unknown_error",
             typeof body2.message === "string" ? body2.message : `Request failed with status ${res.status}`,
@@ -449,6 +452,11 @@ function parseAPI(apiKey, options = {}) {
             typeof body2.request_id === "string" ? body2.request_id : null,
             res.headers.get("Retry-After")
           );
+          if (error.status === 409 && error.code === "ambiguous_city") {
+            const candidates = cityErrorCandidates(body2.candidates);
+            if (candidates) error.candidates = candidates;
+          }
+          throw error;
         }
       } finally {
         clearTimeout(timer);
@@ -521,19 +529,52 @@ function parseAPI(apiKey, options = {}) {
     ),
     district: (code, opts) => request(`/district/${enc(code)}`, { country: opts?.country, state: opts?.state, ...deepQuery(opts) }, void 0, opts),
     city: Object.assign(
-      (name, opts) => request(`/city/${enc(name)}`, { country: opts?.country, state: opts?.state, ...deepQuery(opts) }, void 0, opts),
+      ((name, opts) => request(`/city/${enc(name)}`, { ...cityScopeQuery(opts), ...cityResponseQuery(opts), aliases: opts?.aliases ? "true" : void 0, ambiguity: opts?.ambiguity, ...deepQuery(opts) }, void 0, opts)),
       {
-        id: (id, opts) => request(`/city/id/${enc(id)}`, deepQuery(opts), void 0, opts),
-        search: (query, opts) => request("/city", { q: query, country: opts?.country, state: opts?.state, limit: opts?.limit, ...deepQuery(opts) }, void 0, opts),
-        nearest: (lat, lon, opts) => request("/city", { lat, lon, ...deepQuery(opts) }, void 0, opts),
-        nearby: (name, opts) => request(`/city/${enc(name)}/nearby`, {
+        id: ((id, opts) => request(`/city/id/${enc(id)}`, { hierarchy: opts?.hierarchy ? "true" : void 0, ...cityResponseQuery(opts), ...deepQuery(opts) }, void 0, opts)),
+        search: (async (query, opts) => {
+          const spelling = opts?.match !== void 0 || opts?.maxDistance !== void 0;
+          const result = await request(spelling ? "/city/search" : "/city", { q: query, match: opts?.match, max_distance: opts?.maxDistance, ...cityScopeQuery(opts), ...cityCollectionQuery(opts), ...cityResponseQuery(opts), aliases: opts?.aliases ? "true" : void 0, limit: opts?.limit, ...deepQuery(opts) }, void 0, opts);
+          if (spelling && opts?.format !== "list") {
+            const list = result;
+            return { q: query, ...opts?.country ? { country: opts.country } : {}, ...opts?.state ? { state: opts.state } : {}, cities: list.data, next_cursor: list.next_cursor };
+          }
+          return result;
+        }),
+        /** Canonical list resource. Reuse next_cursor with exactly the same options. */
+        list: (opts) => request("/city", { browse: "true", ...cityScopeQuery(opts), ...cityCollectionQuery(opts), ...cityResponseQuery(opts), format: "list", limit: opts?.limit, ...deepQuery(opts) }, void 0, opts),
+        nearbyCoordinates: (lat, lon, opts) => request("/city", {
+          lat,
+          lon,
+          nearby: "true",
           radius: opts?.radius,
           unit: opts?.unit,
-          country: opts?.country,
-          state: opts?.state,
+          ...cityScopeQuery(opts),
+          ...cityCollectionQuery(opts),
+          ...cityResponseQuery(opts),
+          format: "list",
           limit: opts?.limit,
           ...deepQuery(opts)
-        }, void 0, opts)
+        }, void 0, opts),
+        nearest: ((lat, lon, opts) => request("/city", { lat, lon, ...cityScopeQuery(opts), ...cityResponseQuery(opts), ...deepQuery(opts) }, void 0, opts)),
+        nearby: ((name, opts) => request(`/city/${enc(name)}/nearby`, {
+          radius: opts?.radius,
+          unit: opts?.unit,
+          ...cityScopeQuery(opts),
+          ...cityCollectionQuery(opts),
+          ...cityResponseQuery(opts),
+          aliases: opts?.aliases ? "true" : void 0,
+          ambiguity: opts?.ambiguity,
+          limit: opts?.limit,
+          ...deepQuery(opts)
+        }, void 0, opts)),
+        /** Reviewed immediate children; coverage is partial. */
+        children: (id, opts) => request(`/city/id/${enc(id)}/children`, { limit: opts?.limit, cursor: opts?.cursor, ...cityResponseQuery(opts), hierarchy: opts?.hierarchy ? "true" : void 0, ...deepQuery(opts) }, void 0, opts),
+        /** Immediate parent first, following only reviewed parent facts. */
+        ancestors: (id, opts) => request(`/city/id/${enc(id)}/ancestors`, { ...cityResponseQuery(opts), hierarchy: opts?.hierarchy ? "true" : void 0, ...deepQuery(opts) }, void 0, opts),
+        siblings: (id, opts) => request(`/city/id/${enc(id)}/siblings`, { limit: opts?.limit, cursor: opts?.cursor, ...cityResponseQuery(opts), hierarchy: opts?.hierarchy ? "true" : void 0, ...deepQuery(opts) }, void 0, opts),
+        /** Great-circle distance between stored centers, not travel distance or containment. */
+        distance: (from, to, opts) => request(`/city/id/${enc(from)}/distance/${enc(to)}`, void 0, void 0, opts)
       }
     ),
     /** Look up a postal area. Pass country when known. Check nullable latitude/longitude before another location lookup. */
@@ -729,6 +770,42 @@ function timeTargets(targets, to) {
   }
   return targets.join(",");
 }
+function cityErrorCandidates(input) {
+  if (!Array.isArray(input)) return void 0;
+  const fields = ["name", "name_local", "country", "country_name", "state", "state_name", "type"];
+  return input.slice(0, 2).flatMap((row) => {
+    if (!row || typeof row !== "object" || typeof row.id !== "string" || !/^city_[23456789abcdefghjkmnpqrstuvwxyz]{12}$/.test(row.id)) return [];
+    const candidate = { id: row.id, object: "city" };
+    for (const field of fields) if (Object.hasOwn(row, field) && (row[field] === null || typeof row[field] === "string" && row[field].length <= 255)) candidate[field] = row[field];
+    return [candidate];
+  });
+}
+function cityCsv(value) {
+  return typeof value === "string" ? value : value?.join(",");
+}
+function cityResponseQuery(opts) {
+  return { format: opts?.format, romanized: opts?.romanized ? "true" : void 0 };
+}
+function cityScopeQuery(opts) {
+  return { country: opts?.country, state: opts?.state, type: opts?.type, grain: opts?.grain, hierarchy: opts?.hierarchy ? "true" : void 0 };
+}
+function cityCollectionQuery(opts) {
+  return {
+    min_population: opts?.minPopulation,
+    max_population: opts?.maxPopulation,
+    min_elevation: opts?.minElevation,
+    max_elevation: opts?.maxElevation,
+    countries: cityCsv(opts?.countries),
+    exclude_countries: cityCsv(opts?.excludeCountries),
+    timezones: cityCsv(opts?.timezones),
+    timezone: opts?.timezone,
+    bbox: opts?.bbox,
+    page: opts?.page ? "true" : void 0,
+    cursor: opts?.cursor,
+    sort: opts?.sort,
+    order: opts?.order
+  };
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   EmojiCatalog,

package/dist/index.d.cts

@@ -58,7 +58,7 @@ interface Continent {
     region: string;
     subregion: string;
     population: number | null;
-    /** Reporting year or period for population (YYYY or YYYY-YYYY). Null when unknown or unverifiable. */
+    /** @deprecated No longer returned. Retained for source compatibility. */
     population_period?: string | null;
     area: number | null;
     emoji: string;
@@ -135,7 +135,7 @@ interface StateDistrictItem {
 }
 interface StateDistrictDeep {
     population: number | null;
-    /** Reporting year or period for population (YYYY or YYYY-YYYY). Null when unknown or unverifiable. */
+    /** @deprecated No longer returned. Retained for source compatibility. */
     population_period?: string | null;
 }
 interface StateDistricts {
@@ -160,8 +160,12 @@ interface District {
     deep?: Deep<DistrictDeep>;
 }
 interface City {
+    /** Present for explicit search matching when the server returns suggestion evidence. */
+    match?: CityMatch;
     name: string;
     name_local: string | null;
+    name_romanized?: string | null;
+    romanization_language?: string | null;
     type: string | null;
     state: string | null;
     state_name: string | null;
@@ -174,6 +178,10 @@ interface City {
     timezone: string | null;
     /** Minted parse id (`city_` + 12 chars). Stable pin via `/city/id/{id}`. */
     id: string;
+    /** Returned with hierarchy=true. Null means the layer has not been reviewed. */
+    grain?: CityGrain | null;
+    /** Reviewed immediate parent; null when no reviewed relationship exists. */
+    parent?: CityParent | null;
     deep?: Deep<CityDeep>;
 }
 /** Nearest-city lookups add the distance from the query point. */
@@ -185,7 +193,12 @@ interface CitySearch {
     q: string;
     country?: string;
     state?: string;
+    type?: string;
+    grain?: CityGrain;
+    aliases?: boolean;
     cities: City[];
+    /** Present with page=true or a continuation cursor; null when this is the last page. */
+    next_cursor?: string | null;
 }
 interface CityNearby {
     city: string;
@@ -194,6 +207,7 @@ interface CityNearby {
     radius: number;
     unit: string;
     nearby: CityNearest[];
+    next_cursor?: string | null;
 }
 /** An area's share of ZIP addresses, with category shares measured independently. */
 interface PostalMetro {
@@ -1486,7 +1500,7 @@ interface CountryDeep {
     region: string | null;
     subregion: string | null;
     population: number | null;
-    /** Reporting year or period for population (YYYY or YYYY-YYYY). Null when unknown or unverifiable. */
+    /** @deprecated No longer returned. Retained for source compatibility. */
     population_period?: string | null;
     area: number | null;
     /** Land area in km2. */
@@ -1531,7 +1545,7 @@ interface CountryElevationPoint {
 }
 interface StateDeep {
     population: number | null;
-    /** Reporting year or period for population (YYYY or YYYY-YYYY). Null when unknown or unverifiable. */
+    /** @deprecated No longer returned. Retained for source compatibility. */
     population_period?: string | null;
     /** Total area in km2. */
     area: number | null;
@@ -1545,7 +1559,7 @@ interface StateDeep {
 }
 interface DistrictDeep {
     population: number | null;
-    /** Reporting year or period for population (YYYY or YYYY-YYYY). Null when unknown or unverifiable. */
+    /** @deprecated No longer returned. Retained for source compatibility. */
     population_period?: string | null;
     /** Total area in km2 (land + water, or the official total). */
     area: number | null;
@@ -1563,8 +1577,12 @@ interface CityDeep {
     elevation: number | null;
     elevation_ft: number | null;
     population: number | null;
-    /** Reporting year or period for population (YYYY or YYYY-YYYY). Null when unknown or unverifiable. */
+    /** @deprecated No longer returned. Retained for source compatibility. */
     population_period?: string | null;
+    /** Exact observation date for a reviewed same-grain count; omitted for legacy undated counts. */
+    population_observed_on?: string;
+    /** Published population basis, for example registered_population. */
+    population_basis?: string;
     /** Total area in km2 (land + water, or the official total). */
     area: number | null;
     /** Land area in km2. Null when the source publishes total only. */
@@ -1576,7 +1594,7 @@ interface PostalDeep {
     elevation: number | null;
     elevation_ft: number | null;
     population: number | null;
-    /** Reporting year or period for population (YYYY or YYYY-YYYY). Null when unknown or unverifiable. */
+    /** @deprecated No longer returned. Retained for source compatibility. */
     population_period?: string | null;
     /** Total area in km2. Null when the source has no water split. */
     area: number | null;
@@ -1886,6 +1904,79 @@ interface EmojiConversion {
     text: string;
     unresolved: EmojiUnresolved[];
 }
+type CityGrain = 'municipality' | 'subdivision' | 'locality' | 'metropolitan_area';
+interface CityParent {
+    id: string;
+    name: string | null;
+    name_local: string | null;
+    country: string;
+    state: string | null;
+    type: string | null;
+    grain: CityGrain | null;
+}
+interface CityMatch {
+    type: string;
+    source: string;
+    value: string;
+    language: string | null;
+    edit_distance: number | null;
+}
+interface CityAmbiguityCandidate {
+    id: string;
+    object: 'city';
+    name?: string | null;
+    name_local?: string | null;
+    country?: string | null;
+    country_name?: string | null;
+    state?: string | null;
+    state_name?: string | null;
+    type?: string | null;
+}
+type CityResource = City & {
+    object: 'city';
+    distance?: number;
+    distance_mi?: number;
+};
+interface CityCollection {
+    object: 'list';
+    data: CityResource[];
+    has_more?: boolean;
+    url?: string;
+    /** Opaque, query-bound continuation. Keep the same options on the next call. */
+    next_cursor: string | null;
+    q?: string;
+    country?: string;
+    state?: string | null;
+    type?: string;
+    grain?: CityGrain;
+    aliases?: boolean;
+    city?: string;
+    radius?: number;
+    unit?: string;
+}
+interface CityList extends CityCollection {
+}
+interface CityRelations extends CityCollection {
+    city_id: string;
+    relationship: 'children' | 'ancestors' | 'siblings';
+    coverage: 'partial';
+    parent_id?: string | null;
+}
+interface CityDistance {
+    object: 'city_distance';
+    from: string;
+    to: string;
+    /** Great-circle kilometers between stored centers; null when coordinates are unknown. */
+    distance: number | null;
+    distance_mi: number | null;
+    method: 'great_circle';
+}
+interface CityNearbyCoordinates extends CityCollection {
+    latitude: number;
+    longitude: number;
+    radius: number;
+    unit: string;
+}
 
 /** A proposed task contains operation counts, never lookup inputs. */
 interface PreflightOperation {
@@ -2124,6 +2215,7 @@ declare class ParseAPIError extends Error {
     readonly requestId: string | null;
     /** Original Retry-After response header, when supplied. */
     readonly retryAfter: string | null;
+    candidates?: CityAmbiguityCandidate[];
     constructor(status: number, code: string, message: string, docs: string | null, requestId: string | null, retryAfter?: string | null);
 }
 /** Optional output language for supported display fields. Input parsing stays unchanged. */
@@ -2167,23 +2259,34 @@ type DistrictOptions = LanguageOption & {
     country?: string;
     state?: string;
 } & DeepOption & RequestOptions;
-type CityOptions = LanguageOption & {
-    country?: string;
-    state?: string;
+type CityOptions = LanguageOption & CityScopeOptions & CityResponseOptions & {
+    format?: 'resource';
+    aliases?: boolean;
+    ambiguity?: 'error';
 } & DeepOption & RequestOptions;
-type CityIdOptions = LanguageOption & DeepOption & RequestOptions;
-type CitySearchOptions = LanguageOption & {
-    country?: string;
-    state?: string;
+type CityIdOptions = LanguageOption & CityResponseOptions & {
+    format?: 'resource';
+    hierarchy?: boolean;
+} & DeepOption & RequestOptions;
+type CitySearchOptions = LanguageOption & CityScopeOptions & CityCollectionFilters & CityPagingOptions & CityResponseOptions & {
+    format?: 'list';
+    aliases?: boolean;
     limit?: number;
+    sort?: CitySort;
+    match?: 'exact' | 'prefix' | 'fuzzy';
+    maxDistance?: 1 | 2;
 } & DeepOption & RequestOptions;
-type CityNearestOptions = LanguageOption & DeepOption & RequestOptions;
-type CityNearbyOptions = LanguageOption & {
+type CityNearestOptions = LanguageOption & CityScopeOptions & CityResponseOptions & {
+    format?: 'resource';
+} & DeepOption & RequestOptions;
+type CityNearbyOptions = LanguageOption & CityScopeOptions & CityCollectionFilters & CityPagingOptions & CityResponseOptions & {
+    format?: 'list';
+    aliases?: boolean;
+    ambiguity?: 'error';
     radius?: number;
     unit?: 'km' | 'mi';
-    country?: string;
-    state?: string;
     limit?: number;
+    sort?: CitySort;
 } & DeepOption & RequestOptions;
 /** Pass country when known. Codes shared by multiple countries need it. */
 type PostalOptions = LanguageOption & {
@@ -2452,11 +2555,21 @@ declare function parseAPI(apiKey?: string, options?: ParseAPIOptions): {
         districts: (code: string, opts?: StateDistrictsOptions) => Promise<StateDistricts>;
     };
     district: (code: string, opts?: DistrictOptions) => Promise<District>;
-    city: ((name: string, opts?: CityOptions) => Promise<City>) & {
-        id: (id: string, opts?: CityIdOptions) => Promise<City>;
-        search: (query: string, opts?: CitySearchOptions) => Promise<CitySearch>;
-        nearest: (lat: number, lon: number, opts?: CityNearestOptions) => Promise<CityNearest>;
-        nearby: (name: string, opts?: CityNearbyOptions) => Promise<CityNearby>;
+    city: CityLookupCall & {
+        id: CityIdCall;
+        search: CitySearchCall;
+        /** Canonical list resource. Reuse next_cursor with exactly the same options. */
+        list: (opts?: CityListOptions) => Promise<CityList>;
+        nearbyCoordinates: (lat: number, lon: number, opts?: CityNearbyCoordinatesOptions) => Promise<CityNearbyCoordinates>;
+        nearest: CityNearestCall;
+        nearby: CityNearbyCall;
+        /** Reviewed immediate children; coverage is partial. */
+        children: (id: string, opts?: CityRelationsOptions) => Promise<CityRelations>;
+        /** Immediate parent first, following only reviewed parent facts. */
+        ancestors: (id: string, opts?: CityAncestorsOptions) => Promise<CityRelations>;
+        siblings: (id: string, opts?: CityRelationsOptions) => Promise<CityRelations>;
+        /** Great-circle distance between stored centers, not travel distance or containment. */
+        distance: (from: string, to: string, opts?: CityDistanceOptions) => Promise<CityDistance>;
     };
     /** Look up a postal area. Pass country when known. Check nullable latitude/longitude before another location lookup. */
     postal: ((code: string, opts?: PostalOptions) => Promise<Postal>) & {
@@ -2583,5 +2696,92 @@ type IbanOptions = {
 } & DeepOption & RequestOptions;
 type NpiOptions = LanguageOption & DeepOption & RequestOptions;
 type BinOptions = DeepOption & RequestOptions;
+type CityScopeOptions = {
+    country?: string;
+    state?: string;
+    type?: string;
+    grain?: CityGrain;
+    hierarchy?: boolean;
+};
+type CityResponseOptions = {
+    romanized?: boolean;
+};
+type CityCollectionFilters = {
+    minPopulation?: number;
+    maxPopulation?: number;
+    minElevation?: number;
+    maxElevation?: number;
+    countries?: string | readonly string[];
+    excludeCountries?: string | readonly string[];
+    timezone?: string;
+    timezones?: string | readonly string[];
+    /** Center-coordinate box: west,south,east,north. West > east crosses the date line. */
+    bbox?: string;
+};
+type CityPagingOptions = {
+    page?: boolean;
+    cursor?: string;
+    order?: 'asc' | 'desc';
+};
+type CitySort = string;
+type CityListOptions = LanguageOption & CityScopeOptions & CityCollectionFilters & CityResponseOptions & {
+    limit?: number;
+    cursor?: string;
+    sort?: CitySort;
+    order?: 'asc' | 'desc';
+} & DeepOption & RequestOptions;
+type CityNearbyCoordinatesOptions = LanguageOption & CityScopeOptions & CityCollectionFilters & CityResponseOptions & {
+    radius?: number;
+    unit?: 'km' | 'mi';
+    limit?: number;
+    cursor?: string;
+    sort?: CitySort;
+    order?: 'asc' | 'desc';
+} & DeepOption & RequestOptions;
+type CityRelationsOptions = LanguageOption & CityResponseOptions & {
+    limit?: number;
+    cursor?: string;
+    hierarchy?: boolean;
+} & DeepOption & RequestOptions;
+type CityAncestorsOptions = Omit<CityRelationsOptions, 'limit' | 'cursor'>;
+type CityDistanceOptions = RequestOptions;
+type ClassicCityOptions<T> = T & {
+    format?: never;
+};
+interface CityLookupCall {
+    (name: string, opts?: ClassicCityOptions<CityOptions>): Promise<City>;
+    (name: string, opts: CityOptions & {
+        format: 'resource';
+    }): Promise<CityResource>;
+    (name: string, opts: CityOptions): Promise<City>;
+}
+interface CityIdCall {
+    (id: string, opts?: ClassicCityOptions<CityIdOptions>): Promise<City>;
+    (id: string, opts: CityIdOptions & {
+        format: 'resource';
+    }): Promise<CityResource>;
+    (id: string, opts: CityIdOptions): Promise<City>;
+}
+interface CityNearestCall {
+    (lat: number, lon: number, opts?: ClassicCityOptions<CityNearestOptions>): Promise<CityNearest>;
+    (lat: number, lon: number, opts: CityNearestOptions & {
+        format: 'resource';
+    }): Promise<CityResource & Pick<CityNearest, 'distance' | 'distance_mi'>>;
+    (lat: number, lon: number, opts: CityNearestOptions): Promise<CityNearest>;
+}
+interface CitySearchCall {
+    (query: string, opts?: ClassicCityOptions<CitySearchOptions>): Promise<CitySearch>;
+    (query: string, opts: CitySearchOptions & {
+        format: 'list';
+    }): Promise<CityCollection>;
+    (query: string, opts: CitySearchOptions): Promise<CitySearch | CityCollection>;
+}
+interface CityNearbyCall {
+    (name: string, opts?: ClassicCityOptions<CityNearbyOptions>): Promise<CityNearby>;
+    (name: string, opts: CityNearbyOptions & {
+        format: 'list';
+    }): Promise<CityCollection>;
+    (name: string, opts: CityNearbyOptions): Promise<CityNearby | CityCollection>;
+}
 
-export { type Address, type AddressOptions, type AddressSearch, type AddressSearchOptions, type AddressSuggestion, type AgentTask, type AgentTaskInput, type AgentTaskLookupInput, type AgentTaskResult, type Asn, type AsnOptions, type Bank, type BankChecks, type BankDeep, type BankDirectory, type BankIssue, type BankOptions, type BankRequirementField, type BankRequirements, type BankRequirementsOptions, type BankUsAch, type BankUsAchChecks, type BankUsAchInput, type Bin, type BinOptions, type Bloc, type BlocCountries, type BlocCountriesOptions, type BlocCountryItem, type BlocOptions, type Caller, type CallerOptions, type Card, type CardDeep, type CardOptions, type Carrier, type CarrierDeep, type CarrierOptions, type City, type CityDeep, type CityIdOptions, type CityNearby, type CityNearbyOptions, type CityNearest, type CityNearestOptions, type CityOptions, type CitySearch, type CitySearchOptions, type Company, type CompanyCandidate, type CompanyCountry, type CompanyCoverage, type CompanyCoverageOptions, type CompanyDeep, type CompanyEmailAddress, type CompanyIdOptions, type CompanyMatch, type CompanyOptions, type CompanyPhoneNumber, type CompanyProfile, type CompanyProfileAddress, type CompanyProfileDeep, type CompanyProfileDomain, type CompanyProfileEmail, type CompanyProfileEmployees, type CompanyProfileFounding, type CompanyProfileIdentifier, type CompanyProfileIndustry, type CompanyProfileJurisdiction, type CompanyProfileListing, type CompanyProfilePhone, type CompanyProfileRegistration, type CompanyProfileRegistrationAddress, type CompanyProfileRegistrationLegalForm, type CompanyProfileSource, type CompanyProfileWebsite, type CompanySearch, type CompanySearchOptions, type CompanySocialProfile, type Continent, type ContinentCountries, type ContinentCountriesOptions, type ContinentCountryItem, type ContinentOptions, type Country, type CountryDeep, type CountryElevationPoint, type CountryEmergency, type CountryOptions, type CountryStateItem, type CountryStates, type CountryStatesOptions, type Currency, type CurrencyDeep, type CurrencyOptions, type CurrencyRate, type CurrencyRateOptions, type DateInfo, type DateInfoDeep, type DateOptions, type DateTodayOptions, type Deep, type District, type DistrictDeep, type DistrictOptions, type Dns, type DnsOptions, type DnsRecord, type Domain, type DomainDeep, type DomainOptions, type DomainRegistration, type Elevation, type ElevationLocations, type ElevationOptions, type Email, type EmailDeep, type EmailOptions, type Emoji, type EmojiArtwork, type EmojiArtworkSource, type EmojiBrowse, type EmojiBrowseOptions, EmojiCatalog, type EmojiCatalogConvertOptions, type EmojiCatalogData, EmojiCatalogError, type EmojiCatalogLocalization, type EmojiCatalogLookupOptions, type EmojiCatalogOptions, type EmojiCatalogParseOptions, type EmojiCatalogRegexOptions, type EmojiCatalogScope, type EmojiCatalogSearchFacts, type EmojiCatalogSearchOptions, type EmojiCategories, type EmojiCategory, type EmojiConversion, type EmojiConvertOptions, type EmojiDeep, type EmojiMetadata, type EmojiNativeSearchFacts, type EmojiNotice, type EmojiOptions, type EmojiParse, type EmojiParseOptions, type EmojiPosition, type EmojiSearch, type EmojiSearchOptions, type EmojiShortcodeSourceMetadata, type EmojiSkin, type EmojiSource, type EmojiUnresolved, type EmojiVariant, type Hlr, type HlrDeep, type HlrOptions, type Holiday, type HolidayDate, type HolidayDateOptions, type HolidayOptions, type HolidayYear, type Iban, type IbanDeep, type IbanOptions, type Industry, type IndustryChild, type IndustryCorrection, type IndustryDeep, type IndustryExclusion, type IndustryMatch, type IndustryOptions, type IndustrySearch, type IndustrySearchItem, type IndustrySearchOptions, type Ip, type IpDeep, type IpOptions, type IpSelfOptions, type Language, type LanguageDeep, type LanguageOption, type LanguageOptions, type Mac, type MacOptions, type Measure, type MeasureChoice, type MeasureOptions, type MeasureUnit, type MeasureUnits, type MeasureUnitsOptions, type Mx, type MxOptions, type MxRecord, type Naics, type NaicsChild, type NaicsCorrection, type NaicsDeep, type NaicsExclusion, type NaicsMatch, type NaicsOptions, type NaicsSearch, type NaicsSearchItem, type NaicsSearchOptions, type Name, type NameDeep, type NameOptions, type Npi, type NpiDeep, type NpiEnrollment, type NpiOptions, type ParseAPIClient, ParseAPIError, type ParseAPIOptions, type Phone, type PhoneDeep, type PhoneOptions, type Point, type PointCity, type PointDeep, type PointOptions, type Postal, type PostalDeep, type PostalDistance, type PostalDistanceEnd, type PostalDistanceOptions, type PostalLocality, type PostalMetro, type PostalMetrosDeep, type PostalNearby, type PostalNearbyItem, type PostalNearbyOptions, type PostalOptions, type Preflight, type PreflightCost, type PreflightEmailCapacity, type PreflightOperation, type PreflightOperationEstimate, type PreflightPooledCapacity, type PreflightSpendCapacity, type PreflightTask, type PropertyTax, type Provider, type ProviderDeep, type ProviderEnrollment, type ProviderOptions, type ProviderSource, type ProviderSources, type ProviderTaxonomy, type RequestOptions, type Stack, type StackOptions, type StackTechnology, type State, type StateDeep, type StateDistrictDeep, type StateDistrictItem, type StateDistricts, type StateDistrictsOptions, type StateOptions, type Tariff, type TariffDeep, type TariffMeasure, type TariffOptions, type TariffSearch, type TariffSearchHit, type TariffSearchOptions, type Time, type TimeAtOptions, type TimeLocation, type TimeLocationCandidate, type TimeLocationInput, type TimeOptions, type TimeResolution, type TimeResolutionAlternative, type TimeSeason, type TimeTransition, type TimeTransitionState, type TimeZoneEntry, type TimeZones, type TimeZonesOptions, type Timezone, type TimezoneAtOptions, type TimezoneConversionTarget, type TimezoneConversionTargetDeep, type TimezoneDeep, type TimezoneNextDst, type TimezoneOptions, type Useragent, type UseragentBrowserBrand, type UseragentBrowserDeep, type UseragentDeep, type UseragentDeviceDeep, type UseragentEngineDeep, type UseragentOptions, type UseragentOsDeep, type Vat, type VatAddress, type VatDeep, type VatOptions, type Vehicle, type VehicleDeep, type VehicleOptions, type VehicleRecall, type Vin, type VinDeep, type VinOptions, type VinRecall, type Weather, type WeatherAir, type WeatherAlert, type WeatherCurrent, type WeatherCurrentDeep, type WeatherDay, type WeatherDeep, type WeatherForecastPeriod, type WeatherHistory, type WeatherHour, type WeatherMinute, type WeatherOptions, type WeatherStation, parseAPI };
+export { type Address, type AddressOptions, type AddressSearch, type AddressSearchOptions, type AddressSuggestion, type AgentTask, type AgentTaskInput, type AgentTaskLookupInput, type AgentTaskResult, type Asn, type AsnOptions, type Bank, type BankChecks, type BankDeep, type BankDirectory, type BankIssue, type BankOptions, type BankRequirementField, type BankRequirements, type BankRequirementsOptions, type BankUsAch, type BankUsAchChecks, type BankUsAchInput, type Bin, type BinOptions, type Bloc, type BlocCountries, type BlocCountriesOptions, type BlocCountryItem, type BlocOptions, type Caller, type CallerOptions, type Card, type CardDeep, type CardOptions, type Carrier, type CarrierDeep, type CarrierOptions, type City, type CityAmbiguityCandidate, type CityAncestorsOptions, type CityCollection, type CityCollectionFilters, type CityDeep, type CityDistance, type CityDistanceOptions, type CityGrain, type CityIdCall, type CityIdOptions, type CityList, type CityListOptions, type CityLookupCall, type CityMatch, type CityNearby, type CityNearbyCall, type CityNearbyCoordinates, type CityNearbyCoordinatesOptions, type CityNearbyOptions, type CityNearest, type CityNearestCall, type CityNearestOptions, type CityOptions, type CityPagingOptions, type CityParent, type CityRelations, type CityRelationsOptions, type CityResource, type CityResponseOptions, type CityScopeOptions, type CitySearch, type CitySearchCall, type CitySearchOptions, type CitySort, type Company, type CompanyCandidate, type CompanyCountry, type CompanyCoverage, type CompanyCoverageOptions, type CompanyDeep, type CompanyEmailAddress, type CompanyIdOptions, type CompanyMatch, type CompanyOptions, type CompanyPhoneNumber, type CompanyProfile, type CompanyProfileAddress, type CompanyProfileDeep, type CompanyProfileDomain, type CompanyProfileEmail, type CompanyProfileEmployees, type CompanyProfileFounding, type CompanyProfileIdentifier, type CompanyProfileIndustry, type CompanyProfileJurisdiction, type CompanyProfileListing, type CompanyProfilePhone, type CompanyProfileRegistration, type CompanyProfileRegistrationAddress, type CompanyProfileRegistrationLegalForm, type CompanyProfileSource, type CompanyProfileWebsite, type CompanySearch, type CompanySearchOptions, type CompanySocialProfile, type Continent, type ContinentCountries, type ContinentCountriesOptions, type ContinentCountryItem, type ContinentOptions, type Country, type CountryDeep, type CountryElevationPoint, type CountryEmergency, type CountryOptions, type CountryStateItem, type CountryStates, type CountryStatesOptions, type Currency, type CurrencyDeep, type CurrencyOptions, type CurrencyRate, type CurrencyRateOptions, type DateInfo, type DateInfoDeep, type DateOptions, type DateTodayOptions, type Deep, type District, type DistrictDeep, type DistrictOptions, type Dns, type DnsOptions, type DnsRecord, type Domain, type DomainDeep, type DomainOptions, type DomainRegistration, type Elevation, type ElevationLocations, type ElevationOptions, type Email, type EmailDeep, type EmailOptions, type Emoji, type EmojiArtwork, type EmojiArtworkSource, type EmojiBrowse, type EmojiBrowseOptions, EmojiCatalog, type EmojiCatalogConvertOptions, type EmojiCatalogData, EmojiCatalogError, type EmojiCatalogLocalization, type EmojiCatalogLookupOptions, type EmojiCatalogOptions, type EmojiCatalogParseOptions, type EmojiCatalogRegexOptions, type EmojiCatalogScope, type EmojiCatalogSearchFacts, type EmojiCatalogSearchOptions, type EmojiCategories, type EmojiCategory, type EmojiConversion, type EmojiConvertOptions, type EmojiDeep, type EmojiMetadata, type EmojiNativeSearchFacts, type EmojiNotice, type EmojiOptions, type EmojiParse, type EmojiParseOptions, type EmojiPosition, type EmojiSearch, type EmojiSearchOptions, type EmojiShortcodeSourceMetadata, type EmojiSkin, type EmojiSource, type EmojiUnresolved, type EmojiVariant, type Hlr, type HlrDeep, type HlrOptions, type Holiday, type HolidayDate, type HolidayDateOptions, type HolidayOptions, type HolidayYear, type Iban, type IbanDeep, type IbanOptions, type Industry, type IndustryChild, type IndustryCorrection, type IndustryDeep, type IndustryExclusion, type IndustryMatch, type IndustryOptions, type IndustrySearch, type IndustrySearchItem, type IndustrySearchOptions, type Ip, type IpDeep, type IpOptions, type IpSelfOptions, type Language, type LanguageDeep, type LanguageOption, type LanguageOptions, type Mac, type MacOptions, type Measure, type MeasureChoice, type MeasureOptions, type MeasureUnit, type MeasureUnits, type MeasureUnitsOptions, type Mx, type MxOptions, type MxRecord, type Naics, type NaicsChild, type NaicsCorrection, type NaicsDeep, type NaicsExclusion, type NaicsMatch, type NaicsOptions, type NaicsSearch, type NaicsSearchItem, type NaicsSearchOptions, type Name, type NameDeep, type NameOptions, type Npi, type NpiDeep, type NpiEnrollment, type NpiOptions, type ParseAPIClient, ParseAPIError, type ParseAPIOptions, type Phone, type PhoneDeep, type PhoneOptions, type Point, type PointCity, type PointDeep, type PointOptions, type Postal, type PostalDeep, type PostalDistance, type PostalDistanceEnd, type PostalDistanceOptions, type PostalLocality, type PostalMetro, type PostalMetrosDeep, type PostalNearby, type PostalNearbyItem, type PostalNearbyOptions, type PostalOptions, type Preflight, type PreflightCost, type PreflightEmailCapacity, type PreflightOperation, type PreflightOperationEstimate, type PreflightPooledCapacity, type PreflightSpendCapacity, type PreflightTask, type PropertyTax, type Provider, type ProviderDeep, type ProviderEnrollment, type ProviderOptions, type ProviderSource, type ProviderSources, type ProviderTaxonomy, type RequestOptions, type Stack, type StackOptions, type StackTechnology, type State, type StateDeep, type StateDistrictDeep, type StateDistrictItem, type StateDistricts, type StateDistrictsOptions, type StateOptions, type Tariff, type TariffDeep, type TariffMeasure, type TariffOptions, type TariffSearch, type TariffSearchHit, type TariffSearchOptions, type Time, type TimeAtOptions, type TimeLocation, type TimeLocationCandidate, type TimeLocationInput, type TimeOptions, type TimeResolution, type TimeResolutionAlternative, type TimeSeason, type TimeTransition, type TimeTransitionState, type TimeZoneEntry, type TimeZones, type TimeZonesOptions, type Timezone, type TimezoneAtOptions, type TimezoneConversionTarget, type TimezoneConversionTargetDeep, type TimezoneDeep, type TimezoneNextDst, type TimezoneOptions, type Useragent, type UseragentBrowserBrand, type UseragentBrowserDeep, type UseragentDeep, type UseragentDeviceDeep, type UseragentEngineDeep, type UseragentOptions, type UseragentOsDeep, type Vat, type VatAddress, type VatDeep, type VatOptions, type Vehicle, type VehicleDeep, type VehicleOptions, type VehicleRecall, type Vin, type VinDeep, type VinOptions, type VinRecall, type Weather, type WeatherAir, type WeatherAlert, type WeatherCurrent, type WeatherCurrentDeep, type WeatherDay, type WeatherDeep, type WeatherForecastPeriod, type WeatherHistory, type WeatherHour, type WeatherMinute, type WeatherOptions, type WeatherStation, parseAPI };

package/dist/index.d.ts

@@ -58,7 +58,7 @@ interface Continent {
     region: string;
     subregion: string;
     population: number | null;
-    /** Reporting year or period for population (YYYY or YYYY-YYYY). Null when unknown or unverifiable. */
+    /** @deprecated No longer returned. Retained for source compatibility. */
     population_period?: string | null;
     area: number | null;
     emoji: string;
@@ -135,7 +135,7 @@ interface StateDistrictItem {
 }
 interface StateDistrictDeep {
     population: number | null;
-    /** Reporting year or period for population (YYYY or YYYY-YYYY). Null when unknown or unverifiable. */
+    /** @deprecated No longer returned. Retained for source compatibility. */
     population_period?: string | null;
 }
 interface StateDistricts {
@@ -160,8 +160,12 @@ interface District {
     deep?: Deep<DistrictDeep>;
 }
 interface City {
+    /** Present for explicit search matching when the server returns suggestion evidence. */
+    match?: CityMatch;
     name: string;
     name_local: string | null;
+    name_romanized?: string | null;
+    romanization_language?: string | null;
     type: string | null;
     state: string | null;
     state_name: string | null;
@@ -174,6 +178,10 @@ interface City {
     timezone: string | null;
     /** Minted parse id (`city_` + 12 chars). Stable pin via `/city/id/{id}`. */
     id: string;
+    /** Returned with hierarchy=true. Null means the layer has not been reviewed. */
+    grain?: CityGrain | null;
+    /** Reviewed immediate parent; null when no reviewed relationship exists. */
+    parent?: CityParent | null;
     deep?: Deep<CityDeep>;
 }
 /** Nearest-city lookups add the distance from the query point. */
@@ -185,7 +193,12 @@ interface CitySearch {
     q: string;
     country?: string;
     state?: string;
+    type?: string;
+    grain?: CityGrain;
+    aliases?: boolean;
     cities: City[];
+    /** Present with page=true or a continuation cursor; null when this is the last page. */
+    next_cursor?: string | null;
 }
 interface CityNearby {
     city: string;
@@ -194,6 +207,7 @@ interface CityNearby {
     radius: number;
     unit: string;
     nearby: CityNearest[];
+    next_cursor?: string | null;
 }
 /** An area's share of ZIP addresses, with category shares measured independently. */
 interface PostalMetro {
@@ -1486,7 +1500,7 @@ interface CountryDeep {
     region: string | null;
     subregion: string | null;
     population: number | null;
-    /** Reporting year or period for population (YYYY or YYYY-YYYY). Null when unknown or unverifiable. */
+    /** @deprecated No longer returned. Retained for source compatibility. */
     population_period?: string | null;
     area: number | null;
     /** Land area in km2. */
@@ -1531,7 +1545,7 @@ interface CountryElevationPoint {
 }
 interface StateDeep {
     population: number | null;
-    /** Reporting year or period for population (YYYY or YYYY-YYYY). Null when unknown or unverifiable. */
+    /** @deprecated No longer returned. Retained for source compatibility. */
     population_period?: string | null;
     /** Total area in km2. */
     area: number | null;
@@ -1545,7 +1559,7 @@ interface StateDeep {
 }
 interface DistrictDeep {
     population: number | null;
-    /** Reporting year or period for population (YYYY or YYYY-YYYY). Null when unknown or unverifiable. */
+    /** @deprecated No longer returned. Retained for source compatibility. */
     population_period?: string | null;
     /** Total area in km2 (land + water, or the official total). */
     area: number | null;
@@ -1563,8 +1577,12 @@ interface CityDeep {
     elevation: number | null;
     elevation_ft: number | null;
     population: number | null;
-    /** Reporting year or period for population (YYYY or YYYY-YYYY). Null when unknown or unverifiable. */
+    /** @deprecated No longer returned. Retained for source compatibility. */
     population_period?: string | null;
+    /** Exact observation date for a reviewed same-grain count; omitted for legacy undated counts. */
+    population_observed_on?: string;
+    /** Published population basis, for example registered_population. */
+    population_basis?: string;
     /** Total area in km2 (land + water, or the official total). */
     area: number | null;
     /** Land area in km2. Null when the source publishes total only. */
@@ -1576,7 +1594,7 @@ interface PostalDeep {
     elevation: number | null;
     elevation_ft: number | null;
     population: number | null;
-    /** Reporting year or period for population (YYYY or YYYY-YYYY). Null when unknown or unverifiable. */
+    /** @deprecated No longer returned. Retained for source compatibility. */
     population_period?: string | null;
     /** Total area in km2. Null when the source has no water split. */
     area: number | null;
@@ -1886,6 +1904,79 @@ interface EmojiConversion {
     text: string;
     unresolved: EmojiUnresolved[];
 }
+type CityGrain = 'municipality' | 'subdivision' | 'locality' | 'metropolitan_area';
+interface CityParent {
+    id: string;
+    name: string | null;
+    name_local: string | null;
+    country: string;
+    state: string | null;
+    type: string | null;
+    grain: CityGrain | null;
+}
+interface CityMatch {
+    type: string;
+    source: string;
+    value: string;
+    language: string | null;
+    edit_distance: number | null;
+}
+interface CityAmbiguityCandidate {
+    id: string;
+    object: 'city';
+    name?: string | null;
+    name_local?: string | null;
+    country?: string | null;
+    country_name?: string | null;
+    state?: string | null;
+    state_name?: string | null;
+    type?: string | null;
+}
+type CityResource = City & {
+    object: 'city';
+    distance?: number;
+    distance_mi?: number;
+};
+interface CityCollection {
+    object: 'list';
+    data: CityResource[];
+    has_more?: boolean;
+    url?: string;
+    /** Opaque, query-bound continuation. Keep the same options on the next call. */
+    next_cursor: string | null;
+    q?: string;
+    country?: string;
+    state?: string | null;
+    type?: string;
+    grain?: CityGrain;
+    aliases?: boolean;
+    city?: string;
+    radius?: number;
+    unit?: string;
+}
+interface CityList extends CityCollection {
+}
+interface CityRelations extends CityCollection {
+    city_id: string;
+    relationship: 'children' | 'ancestors' | 'siblings';
+    coverage: 'partial';
+    parent_id?: string | null;
+}
+interface CityDistance {
+    object: 'city_distance';
+    from: string;
+    to: string;
+    /** Great-circle kilometers between stored centers; null when coordinates are unknown. */
+    distance: number | null;
+    distance_mi: number | null;
+    method: 'great_circle';
+}
+interface CityNearbyCoordinates extends CityCollection {
+    latitude: number;
+    longitude: number;
+    radius: number;
+    unit: string;
+}
 
 /** A proposed task contains operation counts, never lookup inputs. */
 interface PreflightOperation {
@@ -2124,6 +2215,7 @@ declare class ParseAPIError extends Error {
     readonly requestId: string | null;
     /** Original Retry-After response header, when supplied. */
     readonly retryAfter: string | null;
+    candidates?: CityAmbiguityCandidate[];
     constructor(status: number, code: string, message: string, docs: string | null, requestId: string | null, retryAfter?: string | null);
 }
 /** Optional output language for supported display fields. Input parsing stays unchanged. */
@@ -2167,23 +2259,34 @@ type DistrictOptions = LanguageOption & {
     country?: string;
     state?: string;
 } & DeepOption & RequestOptions;
-type CityOptions = LanguageOption & {
-    country?: string;
-    state?: string;
+type CityOptions = LanguageOption & CityScopeOptions & CityResponseOptions & {
+    format?: 'resource';
+    aliases?: boolean;
+    ambiguity?: 'error';
 } & DeepOption & RequestOptions;
-type CityIdOptions = LanguageOption & DeepOption & RequestOptions;
-type CitySearchOptions = LanguageOption & {
-    country?: string;
-    state?: string;
+type CityIdOptions = LanguageOption & CityResponseOptions & {
+    format?: 'resource';
+    hierarchy?: boolean;
+} & DeepOption & RequestOptions;
+type CitySearchOptions = LanguageOption & CityScopeOptions & CityCollectionFilters & CityPagingOptions & CityResponseOptions & {
+    format?: 'list';
+    aliases?: boolean;
     limit?: number;
+    sort?: CitySort;
+    match?: 'exact' | 'prefix' | 'fuzzy';
+    maxDistance?: 1 | 2;
 } & DeepOption & RequestOptions;
-type CityNearestOptions = LanguageOption & DeepOption & RequestOptions;
-type CityNearbyOptions = LanguageOption & {
+type CityNearestOptions = LanguageOption & CityScopeOptions & CityResponseOptions & {
+    format?: 'resource';
+} & DeepOption & RequestOptions;
+type CityNearbyOptions = LanguageOption & CityScopeOptions & CityCollectionFilters & CityPagingOptions & CityResponseOptions & {
+    format?: 'list';
+    aliases?: boolean;
+    ambiguity?: 'error';
     radius?: number;
     unit?: 'km' | 'mi';
-    country?: string;
-    state?: string;
     limit?: number;
+    sort?: CitySort;
 } & DeepOption & RequestOptions;
 /** Pass country when known. Codes shared by multiple countries need it. */
 type PostalOptions = LanguageOption & {
@@ -2452,11 +2555,21 @@ declare function parseAPI(apiKey?: string, options?: ParseAPIOptions): {
         districts: (code: string, opts?: StateDistrictsOptions) => Promise<StateDistricts>;
     };
     district: (code: string, opts?: DistrictOptions) => Promise<District>;
-    city: ((name: string, opts?: CityOptions) => Promise<City>) & {
-        id: (id: string, opts?: CityIdOptions) => Promise<City>;
-        search: (query: string, opts?: CitySearchOptions) => Promise<CitySearch>;
-        nearest: (lat: number, lon: number, opts?: CityNearestOptions) => Promise<CityNearest>;
-        nearby: (name: string, opts?: CityNearbyOptions) => Promise<CityNearby>;
+    city: CityLookupCall & {
+        id: CityIdCall;
+        search: CitySearchCall;
+        /** Canonical list resource. Reuse next_cursor with exactly the same options. */
+        list: (opts?: CityListOptions) => Promise<CityList>;
+        nearbyCoordinates: (lat: number, lon: number, opts?: CityNearbyCoordinatesOptions) => Promise<CityNearbyCoordinates>;
+        nearest: CityNearestCall;
+        nearby: CityNearbyCall;
+        /** Reviewed immediate children; coverage is partial. */
+        children: (id: string, opts?: CityRelationsOptions) => Promise<CityRelations>;
+        /** Immediate parent first, following only reviewed parent facts. */
+        ancestors: (id: string, opts?: CityAncestorsOptions) => Promise<CityRelations>;
+        siblings: (id: string, opts?: CityRelationsOptions) => Promise<CityRelations>;
+        /** Great-circle distance between stored centers, not travel distance or containment. */
+        distance: (from: string, to: string, opts?: CityDistanceOptions) => Promise<CityDistance>;
     };
     /** Look up a postal area. Pass country when known. Check nullable latitude/longitude before another location lookup. */
     postal: ((code: string, opts?: PostalOptions) => Promise<Postal>) & {
@@ -2583,5 +2696,92 @@ type IbanOptions = {
 } & DeepOption & RequestOptions;
 type NpiOptions = LanguageOption & DeepOption & RequestOptions;
 type BinOptions = DeepOption & RequestOptions;
+type CityScopeOptions = {
+    country?: string;
+    state?: string;
+    type?: string;
+    grain?: CityGrain;
+    hierarchy?: boolean;
+};
+type CityResponseOptions = {
+    romanized?: boolean;
+};
+type CityCollectionFilters = {
+    minPopulation?: number;
+    maxPopulation?: number;
+    minElevation?: number;
+    maxElevation?: number;
+    countries?: string | readonly string[];
+    excludeCountries?: string | readonly string[];
+    timezone?: string;
+    timezones?: string | readonly string[];
+    /** Center-coordinate box: west,south,east,north. West > east crosses the date line. */
+    bbox?: string;
+};
+type CityPagingOptions = {
+    page?: boolean;
+    cursor?: string;
+    order?: 'asc' | 'desc';
+};
+type CitySort = string;
+type CityListOptions = LanguageOption & CityScopeOptions & CityCollectionFilters & CityResponseOptions & {
+    limit?: number;
+    cursor?: string;
+    sort?: CitySort;
+    order?: 'asc' | 'desc';
+} & DeepOption & RequestOptions;
+type CityNearbyCoordinatesOptions = LanguageOption & CityScopeOptions & CityCollectionFilters & CityResponseOptions & {
+    radius?: number;
+    unit?: 'km' | 'mi';
+    limit?: number;
+    cursor?: string;
+    sort?: CitySort;
+    order?: 'asc' | 'desc';
+} & DeepOption & RequestOptions;
+type CityRelationsOptions = LanguageOption & CityResponseOptions & {
+    limit?: number;
+    cursor?: string;
+    hierarchy?: boolean;
+} & DeepOption & RequestOptions;
+type CityAncestorsOptions = Omit<CityRelationsOptions, 'limit' | 'cursor'>;
+type CityDistanceOptions = RequestOptions;
+type ClassicCityOptions<T> = T & {
+    format?: never;
+};
+interface CityLookupCall {
+    (name: string, opts?: ClassicCityOptions<CityOptions>): Promise<City>;
+    (name: string, opts: CityOptions & {
+        format: 'resource';
+    }): Promise<CityResource>;
+    (name: string, opts: CityOptions): Promise<City>;
+}
+interface CityIdCall {
+    (id: string, opts?: ClassicCityOptions<CityIdOptions>): Promise<City>;
+    (id: string, opts: CityIdOptions & {
+        format: 'resource';
+    }): Promise<CityResource>;
+    (id: string, opts: CityIdOptions): Promise<City>;
+}
+interface CityNearestCall {
+    (lat: number, lon: number, opts?: ClassicCityOptions<CityNearestOptions>): Promise<CityNearest>;
+    (lat: number, lon: number, opts: CityNearestOptions & {
+        format: 'resource';
+    }): Promise<CityResource & Pick<CityNearest, 'distance' | 'distance_mi'>>;
+    (lat: number, lon: number, opts: CityNearestOptions): Promise<CityNearest>;
+}
+interface CitySearchCall {
+    (query: string, opts?: ClassicCityOptions<CitySearchOptions>): Promise<CitySearch>;
+    (query: string, opts: CitySearchOptions & {
+        format: 'list';
+    }): Promise<CityCollection>;
+    (query: string, opts: CitySearchOptions): Promise<CitySearch | CityCollection>;
+}
+interface CityNearbyCall {
+    (name: string, opts?: ClassicCityOptions<CityNearbyOptions>): Promise<CityNearby>;
+    (name: string, opts: CityNearbyOptions & {
+        format: 'list';
+    }): Promise<CityCollection>;
+    (name: string, opts: CityNearbyOptions): Promise<CityNearby | CityCollection>;
+}
 
-export { type Address, type AddressOptions, type AddressSearch, type AddressSearchOptions, type AddressSuggestion, type AgentTask, type AgentTaskInput, type AgentTaskLookupInput, type AgentTaskResult, type Asn, type AsnOptions, type Bank, type BankChecks, type BankDeep, type BankDirectory, type BankIssue, type BankOptions, type BankRequirementField, type BankRequirements, type BankRequirementsOptions, type BankUsAch, type BankUsAchChecks, type BankUsAchInput, type Bin, type BinOptions, type Bloc, type BlocCountries, type BlocCountriesOptions, type BlocCountryItem, type BlocOptions, type Caller, type CallerOptions, type Card, type CardDeep, type CardOptions, type Carrier, type CarrierDeep, type CarrierOptions, type City, type CityDeep, type CityIdOptions, type CityNearby, type CityNearbyOptions, type CityNearest, type CityNearestOptions, type CityOptions, type CitySearch, type CitySearchOptions, type Company, type CompanyCandidate, type CompanyCountry, type CompanyCoverage, type CompanyCoverageOptions, type CompanyDeep, type CompanyEmailAddress, type CompanyIdOptions, type CompanyMatch, type CompanyOptions, type CompanyPhoneNumber, type CompanyProfile, type CompanyProfileAddress, type CompanyProfileDeep, type CompanyProfileDomain, type CompanyProfileEmail, type CompanyProfileEmployees, type CompanyProfileFounding, type CompanyProfileIdentifier, type CompanyProfileIndustry, type CompanyProfileJurisdiction, type CompanyProfileListing, type CompanyProfilePhone, type CompanyProfileRegistration, type CompanyProfileRegistrationAddress, type CompanyProfileRegistrationLegalForm, type CompanyProfileSource, type CompanyProfileWebsite, type CompanySearch, type CompanySearchOptions, type CompanySocialProfile, type Continent, type ContinentCountries, type ContinentCountriesOptions, type ContinentCountryItem, type ContinentOptions, type Country, type CountryDeep, type CountryElevationPoint, type CountryEmergency, type CountryOptions, type CountryStateItem, type CountryStates, type CountryStatesOptions, type Currency, type CurrencyDeep, type CurrencyOptions, type CurrencyRate, type CurrencyRateOptions, type DateInfo, type DateInfoDeep, type DateOptions, type DateTodayOptions, type Deep, type District, type DistrictDeep, type DistrictOptions, type Dns, type DnsOptions, type DnsRecord, type Domain, type DomainDeep, type DomainOptions, type DomainRegistration, type Elevation, type ElevationLocations, type ElevationOptions, type Email, type EmailDeep, type EmailOptions, type Emoji, type EmojiArtwork, type EmojiArtworkSource, type EmojiBrowse, type EmojiBrowseOptions, EmojiCatalog, type EmojiCatalogConvertOptions, type EmojiCatalogData, EmojiCatalogError, type EmojiCatalogLocalization, type EmojiCatalogLookupOptions, type EmojiCatalogOptions, type EmojiCatalogParseOptions, type EmojiCatalogRegexOptions, type EmojiCatalogScope, type EmojiCatalogSearchFacts, type EmojiCatalogSearchOptions, type EmojiCategories, type EmojiCategory, type EmojiConversion, type EmojiConvertOptions, type EmojiDeep, type EmojiMetadata, type EmojiNativeSearchFacts, type EmojiNotice, type EmojiOptions, type EmojiParse, type EmojiParseOptions, type EmojiPosition, type EmojiSearch, type EmojiSearchOptions, type EmojiShortcodeSourceMetadata, type EmojiSkin, type EmojiSource, type EmojiUnresolved, type EmojiVariant, type Hlr, type HlrDeep, type HlrOptions, type Holiday, type HolidayDate, type HolidayDateOptions, type HolidayOptions, type HolidayYear, type Iban, type IbanDeep, type IbanOptions, type Industry, type IndustryChild, type IndustryCorrection, type IndustryDeep, type IndustryExclusion, type IndustryMatch, type IndustryOptions, type IndustrySearch, type IndustrySearchItem, type IndustrySearchOptions, type Ip, type IpDeep, type IpOptions, type IpSelfOptions, type Language, type LanguageDeep, type LanguageOption, type LanguageOptions, type Mac, type MacOptions, type Measure, type MeasureChoice, type MeasureOptions, type MeasureUnit, type MeasureUnits, type MeasureUnitsOptions, type Mx, type MxOptions, type MxRecord, type Naics, type NaicsChild, type NaicsCorrection, type NaicsDeep, type NaicsExclusion, type NaicsMatch, type NaicsOptions, type NaicsSearch, type NaicsSearchItem, type NaicsSearchOptions, type Name, type NameDeep, type NameOptions, type Npi, type NpiDeep, type NpiEnrollment, type NpiOptions, type ParseAPIClient, ParseAPIError, type ParseAPIOptions, type Phone, type PhoneDeep, type PhoneOptions, type Point, type PointCity, type PointDeep, type PointOptions, type Postal, type PostalDeep, type PostalDistance, type PostalDistanceEnd, type PostalDistanceOptions, type PostalLocality, type PostalMetro, type PostalMetrosDeep, type PostalNearby, type PostalNearbyItem, type PostalNearbyOptions, type PostalOptions, type Preflight, type PreflightCost, type PreflightEmailCapacity, type PreflightOperation, type PreflightOperationEstimate, type PreflightPooledCapacity, type PreflightSpendCapacity, type PreflightTask, type PropertyTax, type Provider, type ProviderDeep, type ProviderEnrollment, type ProviderOptions, type ProviderSource, type ProviderSources, type ProviderTaxonomy, type RequestOptions, type Stack, type StackOptions, type StackTechnology, type State, type StateDeep, type StateDistrictDeep, type StateDistrictItem, type StateDistricts, type StateDistrictsOptions, type StateOptions, type Tariff, type TariffDeep, type TariffMeasure, type TariffOptions, type TariffSearch, type TariffSearchHit, type TariffSearchOptions, type Time, type TimeAtOptions, type TimeLocation, type TimeLocationCandidate, type TimeLocationInput, type TimeOptions, type TimeResolution, type TimeResolutionAlternative, type TimeSeason, type TimeTransition, type TimeTransitionState, type TimeZoneEntry, type TimeZones, type TimeZonesOptions, type Timezone, type TimezoneAtOptions, type TimezoneConversionTarget, type TimezoneConversionTargetDeep, type TimezoneDeep, type TimezoneNextDst, type TimezoneOptions, type Useragent, type UseragentBrowserBrand, type UseragentBrowserDeep, type UseragentDeep, type UseragentDeviceDeep, type UseragentEngineDeep, type UseragentOptions, type UseragentOsDeep, type Vat, type VatAddress, type VatDeep, type VatOptions, type Vehicle, type VehicleDeep, type VehicleOptions, type VehicleRecall, type Vin, type VinDeep, type VinOptions, type VinRecall, type Weather, type WeatherAir, type WeatherAlert, type WeatherCurrent, type WeatherCurrentDeep, type WeatherDay, type WeatherDeep, type WeatherForecastPeriod, type WeatherHistory, type WeatherHour, type WeatherMinute, type WeatherOptions, type WeatherStation, parseAPI };
+export { type Address, type AddressOptions, type AddressSearch, type AddressSearchOptions, type AddressSuggestion, type AgentTask, type AgentTaskInput, type AgentTaskLookupInput, type AgentTaskResult, type Asn, type AsnOptions, type Bank, type BankChecks, type BankDeep, type BankDirectory, type BankIssue, type BankOptions, type BankRequirementField, type BankRequirements, type BankRequirementsOptions, type BankUsAch, type BankUsAchChecks, type BankUsAchInput, type Bin, type BinOptions, type Bloc, type BlocCountries, type BlocCountriesOptions, type BlocCountryItem, type BlocOptions, type Caller, type CallerOptions, type Card, type CardDeep, type CardOptions, type Carrier, type CarrierDeep, type CarrierOptions, type City, type CityAmbiguityCandidate, type CityAncestorsOptions, type CityCollection, type CityCollectionFilters, type CityDeep, type CityDistance, type CityDistanceOptions, type CityGrain, type CityIdCall, type CityIdOptions, type CityList, type CityListOptions, type CityLookupCall, type CityMatch, type CityNearby, type CityNearbyCall, type CityNearbyCoordinates, type CityNearbyCoordinatesOptions, type CityNearbyOptions, type CityNearest, type CityNearestCall, type CityNearestOptions, type CityOptions, type CityPagingOptions, type CityParent, type CityRelations, type CityRelationsOptions, type CityResource, type CityResponseOptions, type CityScopeOptions, type CitySearch, type CitySearchCall, type CitySearchOptions, type CitySort, type Company, type CompanyCandidate, type CompanyCountry, type CompanyCoverage, type CompanyCoverageOptions, type CompanyDeep, type CompanyEmailAddress, type CompanyIdOptions, type CompanyMatch, type CompanyOptions, type CompanyPhoneNumber, type CompanyProfile, type CompanyProfileAddress, type CompanyProfileDeep, type CompanyProfileDomain, type CompanyProfileEmail, type CompanyProfileEmployees, type CompanyProfileFounding, type CompanyProfileIdentifier, type CompanyProfileIndustry, type CompanyProfileJurisdiction, type CompanyProfileListing, type CompanyProfilePhone, type CompanyProfileRegistration, type CompanyProfileRegistrationAddress, type CompanyProfileRegistrationLegalForm, type CompanyProfileSource, type CompanyProfileWebsite, type CompanySearch, type CompanySearchOptions, type CompanySocialProfile, type Continent, type ContinentCountries, type ContinentCountriesOptions, type ContinentCountryItem, type ContinentOptions, type Country, type CountryDeep, type CountryElevationPoint, type CountryEmergency, type CountryOptions, type CountryStateItem, type CountryStates, type CountryStatesOptions, type Currency, type CurrencyDeep, type CurrencyOptions, type CurrencyRate, type CurrencyRateOptions, type DateInfo, type DateInfoDeep, type DateOptions, type DateTodayOptions, type Deep, type District, type DistrictDeep, type DistrictOptions, type Dns, type DnsOptions, type DnsRecord, type Domain, type DomainDeep, type DomainOptions, type DomainRegistration, type Elevation, type ElevationLocations, type ElevationOptions, type Email, type EmailDeep, type EmailOptions, type Emoji, type EmojiArtwork, type EmojiArtworkSource, type EmojiBrowse, type EmojiBrowseOptions, EmojiCatalog, type EmojiCatalogConvertOptions, type EmojiCatalogData, EmojiCatalogError, type EmojiCatalogLocalization, type EmojiCatalogLookupOptions, type EmojiCatalogOptions, type EmojiCatalogParseOptions, type EmojiCatalogRegexOptions, type EmojiCatalogScope, type EmojiCatalogSearchFacts, type EmojiCatalogSearchOptions, type EmojiCategories, type EmojiCategory, type EmojiConversion, type EmojiConvertOptions, type EmojiDeep, type EmojiMetadata, type EmojiNativeSearchFacts, type EmojiNotice, type EmojiOptions, type EmojiParse, type EmojiParseOptions, type EmojiPosition, type EmojiSearch, type EmojiSearchOptions, type EmojiShortcodeSourceMetadata, type EmojiSkin, type EmojiSource, type EmojiUnresolved, type EmojiVariant, type Hlr, type HlrDeep, type HlrOptions, type Holiday, type HolidayDate, type HolidayDateOptions, type HolidayOptions, type HolidayYear, type Iban, type IbanDeep, type IbanOptions, type Industry, type IndustryChild, type IndustryCorrection, type IndustryDeep, type IndustryExclusion, type IndustryMatch, type IndustryOptions, type IndustrySearch, type IndustrySearchItem, type IndustrySearchOptions, type Ip, type IpDeep, type IpOptions, type IpSelfOptions, type Language, type LanguageDeep, type LanguageOption, type LanguageOptions, type Mac, type MacOptions, type Measure, type MeasureChoice, type MeasureOptions, type MeasureUnit, type MeasureUnits, type MeasureUnitsOptions, type Mx, type MxOptions, type MxRecord, type Naics, type NaicsChild, type NaicsCorrection, type NaicsDeep, type NaicsExclusion, type NaicsMatch, type NaicsOptions, type NaicsSearch, type NaicsSearchItem, type NaicsSearchOptions, type Name, type NameDeep, type NameOptions, type Npi, type NpiDeep, type NpiEnrollment, type NpiOptions, type ParseAPIClient, ParseAPIError, type ParseAPIOptions, type Phone, type PhoneDeep, type PhoneOptions, type Point, type PointCity, type PointDeep, type PointOptions, type Postal, type PostalDeep, type PostalDistance, type PostalDistanceEnd, type PostalDistanceOptions, type PostalLocality, type PostalMetro, type PostalMetrosDeep, type PostalNearby, type PostalNearbyItem, type PostalNearbyOptions, type PostalOptions, type Preflight, type PreflightCost, type PreflightEmailCapacity, type PreflightOperation, type PreflightOperationEstimate, type PreflightPooledCapacity, type PreflightSpendCapacity, type PreflightTask, type PropertyTax, type Provider, type ProviderDeep, type ProviderEnrollment, type ProviderOptions, type ProviderSource, type ProviderSources, type ProviderTaxonomy, type RequestOptions, type Stack, type StackOptions, type StackTechnology, type State, type StateDeep, type StateDistrictDeep, type StateDistrictItem, type StateDistricts, type StateDistrictsOptions, type StateOptions, type Tariff, type TariffDeep, type TariffMeasure, type TariffOptions, type TariffSearch, type TariffSearchHit, type TariffSearchOptions, type Time, type TimeAtOptions, type TimeLocation, type TimeLocationCandidate, type TimeLocationInput, type TimeOptions, type TimeResolution, type TimeResolutionAlternative, type TimeSeason, type TimeTransition, type TimeTransitionState, type TimeZoneEntry, type TimeZones, type TimeZonesOptions, type Timezone, type TimezoneAtOptions, type TimezoneConversionTarget, type TimezoneConversionTargetDeep, type TimezoneDeep, type TimezoneNextDst, type TimezoneOptions, type Useragent, type UseragentBrowserBrand, type UseragentBrowserDeep, type UseragentDeep, type UseragentDeviceDeep, type UseragentEngineDeep, type UseragentOptions, type UseragentOsDeep, type Vat, type VatAddress, type VatDeep, type VatOptions, type Vehicle, type VehicleDeep, type VehicleOptions, type VehicleRecall, type Vin, type VinDeep, type VinOptions, type VinRecall, type Weather, type WeatherAir, type WeatherAlert, type WeatherCurrent, type WeatherCurrentDeep, type WeatherDay, type WeatherDeep, type WeatherForecastPeriod, type WeatherHistory, type WeatherHour, type WeatherMinute, type WeatherOptions, type WeatherStation, parseAPI };

package/dist/index.js

@@ -256,7 +256,7 @@ var EmojiCatalog = class {
 };
 
 // src/index.ts
-var VERSION = "1.10.5";
+var VERSION = "1.11.0";
 var API_VERSION = "2.0.0";
 var DEFAULT_BASE_URL = "https://api.parseapi.com";
 var DEFAULT_TIMEOUT_MS = 1e4;
@@ -284,8 +284,11 @@ var ParseAPIError = class extends Error {
     this.retryAfter = retryAfter;
   }
 };
+function tariffEditionId(value) {
+  return typeof value === "string" && (value.length === 64 && /^[a-f0-9]{64}$/.test(value) || /^ted_[1-9][0-9]{0,19}(?![\s\S])/.test(value) && (value.length < 24 || value.slice(4) <= "18446744073709551615"));
+}
 function tariffSelection(result, opts) {
-  if ((opts?.edition !== void 0 || opts?.date !== void 0) && (typeof result.edition !== "string" || result.edition.length !== 64 || !/^[a-f0-9]{64}$/.test(result.edition) || opts.edition !== void 0 && result.edition !== opts.edition || (opts.date !== void 0 ? result.date !== opts.date : result.date != null))) {
+  if ((opts?.edition !== void 0 || opts?.date !== void 0) && (!tariffEditionId(result.edition) || opts.edition !== void 0 && result.edition !== opts.edition || (opts.date !== void 0 ? result.date !== opts.date : result.date != null))) {
     throw new ParseAPIError(0, "tariff_selection_mismatch", "Tariff response did not confirm the requested edition/date. The server may not support this selection.", null, null);
   }
   return result;
@@ -412,7 +415,7 @@ function parseAPI(apiKey, options = {}) {
             controller.signal.throwIfAborted();
           }
           signal?.throwIfAborted();
-          throw new ParseAPIError(
+          const error = new ParseAPIError(
             res.status,
             typeof body2.code === "string" ? body2.code : "unknown_error",
             typeof body2.message === "string" ? body2.message : `Request failed with status ${res.status}`,
@@ -420,6 +423,11 @@ function parseAPI(apiKey, options = {}) {
             typeof body2.request_id === "string" ? body2.request_id : null,
             res.headers.get("Retry-After")
           );
+          if (error.status === 409 && error.code === "ambiguous_city") {
+            const candidates = cityErrorCandidates(body2.candidates);
+            if (candidates) error.candidates = candidates;
+          }
+          throw error;
         }
       } finally {
         clearTimeout(timer);
@@ -492,19 +500,52 @@ function parseAPI(apiKey, options = {}) {
     ),
     district: (code, opts) => request(`/district/${enc(code)}`, { country: opts?.country, state: opts?.state, ...deepQuery(opts) }, void 0, opts),
     city: Object.assign(
-      (name, opts) => request(`/city/${enc(name)}`, { country: opts?.country, state: opts?.state, ...deepQuery(opts) }, void 0, opts),
+      ((name, opts) => request(`/city/${enc(name)}`, { ...cityScopeQuery(opts), ...cityResponseQuery(opts), aliases: opts?.aliases ? "true" : void 0, ambiguity: opts?.ambiguity, ...deepQuery(opts) }, void 0, opts)),
       {
-        id: (id, opts) => request(`/city/id/${enc(id)}`, deepQuery(opts), void 0, opts),
-        search: (query, opts) => request("/city", { q: query, country: opts?.country, state: opts?.state, limit: opts?.limit, ...deepQuery(opts) }, void 0, opts),
-        nearest: (lat, lon, opts) => request("/city", { lat, lon, ...deepQuery(opts) }, void 0, opts),
-        nearby: (name, opts) => request(`/city/${enc(name)}/nearby`, {
+        id: ((id, opts) => request(`/city/id/${enc(id)}`, { hierarchy: opts?.hierarchy ? "true" : void 0, ...cityResponseQuery(opts), ...deepQuery(opts) }, void 0, opts)),
+        search: (async (query, opts) => {
+          const spelling = opts?.match !== void 0 || opts?.maxDistance !== void 0;
+          const result = await request(spelling ? "/city/search" : "/city", { q: query, match: opts?.match, max_distance: opts?.maxDistance, ...cityScopeQuery(opts), ...cityCollectionQuery(opts), ...cityResponseQuery(opts), aliases: opts?.aliases ? "true" : void 0, limit: opts?.limit, ...deepQuery(opts) }, void 0, opts);
+          if (spelling && opts?.format !== "list") {
+            const list = result;
+            return { q: query, ...opts?.country ? { country: opts.country } : {}, ...opts?.state ? { state: opts.state } : {}, cities: list.data, next_cursor: list.next_cursor };
+          }
+          return result;
+        }),
+        /** Canonical list resource. Reuse next_cursor with exactly the same options. */
+        list: (opts) => request("/city", { browse: "true", ...cityScopeQuery(opts), ...cityCollectionQuery(opts), ...cityResponseQuery(opts), format: "list", limit: opts?.limit, ...deepQuery(opts) }, void 0, opts),
+        nearbyCoordinates: (lat, lon, opts) => request("/city", {
+          lat,
+          lon,
+          nearby: "true",
           radius: opts?.radius,
           unit: opts?.unit,
-          country: opts?.country,
-          state: opts?.state,
+          ...cityScopeQuery(opts),
+          ...cityCollectionQuery(opts),
+          ...cityResponseQuery(opts),
+          format: "list",
           limit: opts?.limit,
           ...deepQuery(opts)
-        }, void 0, opts)
+        }, void 0, opts),
+        nearest: ((lat, lon, opts) => request("/city", { lat, lon, ...cityScopeQuery(opts), ...cityResponseQuery(opts), ...deepQuery(opts) }, void 0, opts)),
+        nearby: ((name, opts) => request(`/city/${enc(name)}/nearby`, {
+          radius: opts?.radius,
+          unit: opts?.unit,
+          ...cityScopeQuery(opts),
+          ...cityCollectionQuery(opts),
+          ...cityResponseQuery(opts),
+          aliases: opts?.aliases ? "true" : void 0,
+          ambiguity: opts?.ambiguity,
+          limit: opts?.limit,
+          ...deepQuery(opts)
+        }, void 0, opts)),
+        /** Reviewed immediate children; coverage is partial. */
+        children: (id, opts) => request(`/city/id/${enc(id)}/children`, { limit: opts?.limit, cursor: opts?.cursor, ...cityResponseQuery(opts), hierarchy: opts?.hierarchy ? "true" : void 0, ...deepQuery(opts) }, void 0, opts),
+        /** Immediate parent first, following only reviewed parent facts. */
+        ancestors: (id, opts) => request(`/city/id/${enc(id)}/ancestors`, { ...cityResponseQuery(opts), hierarchy: opts?.hierarchy ? "true" : void 0, ...deepQuery(opts) }, void 0, opts),
+        siblings: (id, opts) => request(`/city/id/${enc(id)}/siblings`, { limit: opts?.limit, cursor: opts?.cursor, ...cityResponseQuery(opts), hierarchy: opts?.hierarchy ? "true" : void 0, ...deepQuery(opts) }, void 0, opts),
+        /** Great-circle distance between stored centers, not travel distance or containment. */
+        distance: (from, to, opts) => request(`/city/id/${enc(from)}/distance/${enc(to)}`, void 0, void 0, opts)
       }
     ),
     /** Look up a postal area. Pass country when known. Check nullable latitude/longitude before another location lookup. */
@@ -700,6 +741,42 @@ function timeTargets(targets, to) {
   }
   return targets.join(",");
 }
+function cityErrorCandidates(input) {
+  if (!Array.isArray(input)) return void 0;
+  const fields = ["name", "name_local", "country", "country_name", "state", "state_name", "type"];
+  return input.slice(0, 2).flatMap((row) => {
+    if (!row || typeof row !== "object" || typeof row.id !== "string" || !/^city_[23456789abcdefghjkmnpqrstuvwxyz]{12}$/.test(row.id)) return [];
+    const candidate = { id: row.id, object: "city" };
+    for (const field of fields) if (Object.hasOwn(row, field) && (row[field] === null || typeof row[field] === "string" && row[field].length <= 255)) candidate[field] = row[field];
+    return [candidate];
+  });
+}
+function cityCsv(value) {
+  return typeof value === "string" ? value : value?.join(",");
+}
+function cityResponseQuery(opts) {
+  return { format: opts?.format, romanized: opts?.romanized ? "true" : void 0 };
+}
+function cityScopeQuery(opts) {
+  return { country: opts?.country, state: opts?.state, type: opts?.type, grain: opts?.grain, hierarchy: opts?.hierarchy ? "true" : void 0 };
+}
+function cityCollectionQuery(opts) {
+  return {
+    min_population: opts?.minPopulation,
+    max_population: opts?.maxPopulation,
+    min_elevation: opts?.minElevation,
+    max_elevation: opts?.maxElevation,
+    countries: cityCsv(opts?.countries),
+    exclude_countries: cityCsv(opts?.excludeCountries),
+    timezones: cityCsv(opts?.timezones),
+    timezone: opts?.timezone,
+    bbox: opts?.bbox,
+    page: opts?.page ? "true" : void 0,
+    cursor: opts?.cursor,
+    sort: opts?.sort,
+    order: opts?.order
+  };
+}
 export {
   EmojiCatalog,
   EmojiCatalogError,

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@parseapi/sdk",
-	"version": "1.10.5",
+	"version": "1.11.0",
 	"description": "Official ParseAPI client for Node and TypeScript. One key, minimal JSON, fast.",
 	"keywords": [
 		"parseapi",