Complete v3 reference for CountryStateCity collection, canonical-entity, search, spatial, timezone, coverage, and export APIs.

import {
  CountryStateCity,
  PolygonLookupIndex,
  locatePointInPolygons,
} from '@tansuasici/country-state-city';

Collection methods return typed objects when format is omitted and a serialized string for json, csv, xml, or yaml. Methods that accept options pass FormatOptions to the formatter.

Countries

CountryStateCity.getAllCountries(format?, options?);
CountryStateCity.getCountryById(id);
CountryStateCity.getCountryByIso2(iso2);
CountryStateCity.getCountryByIso3(iso3);
CountryStateCity.searchCountries(query);
CountryStateCity.getCountriesByRegion(region);
CountryStateCity.getCountriesBySubregion(subregion);
CountryStateCity.getCountryTranslation(countryCode, locale);

getCountryById, getCountryByIso2, and getCountryByIso3 return Country | undefined. getCountryTranslation accepts the canonical locale keys plus the migration aliases br, cn, and kr, and returns string | null | undefined.

const turkey = CountryStateCity.getCountryByIso2('TR');
const european = CountryStateCity.getCountriesByRegion('Europe');
const germanName = CountryStateCity.getCountryTranslation('DE', 'tr');

States and cities

CountryStateCity.getAllStates(format?, options?);
CountryStateCity.getStateById(id);
CountryStateCity.getStatesByCountryId(countryId, format?, options?);
CountryStateCity.getStatesByCountryCode(countryCode, format?, options?);
CountryStateCity.searchStates(query, countryId?);

CountryStateCity.getAllCities(format?, options?);
CountryStateCity.getCityById(id);
CountryStateCity.getCitiesByStateId(stateId, format?, options?);
CountryStateCity.getCitiesByCountryId(countryId, format?, options?);
CountryStateCity.searchCities(query, stateId?, countryId?);

const provinces = CountryStateCity.getStatesByCountryCode('TR');
const istanbulPlaces = CountryStateCity.getCitiesByStateId(2170);

getAllCities() reconstructs all 147,739 place records. Prefer a country/state filter or ranked search when the full collection is unnecessary.

Canonical administrative areas and settlements

The imported state/city collections remain available for compatibility. Use these methods when the semantic entity layer matters:

CountryStateCity.getAdministrativeAreas({
  countryCode?: string,
  level?: number, // defaults to 1
  lifecycleStatus?: 'current' | 'historical' | 'review-required' | 'all',
  sourceLayer?: 'state' | 'city' | 'all', // defaults to state
});

CountryStateCity.getSettlements({
  countryCode?: string,
  stateId?: number,
  lifecycleStatus?: 'current' | 'historical' | 'review-required' | 'all',
});

getAdministrativeAreas() returns Array<State | City>. getSettlements() returns City[] and excludes source-city rows classified as administrative areas.

Türkiye districts

The explicit district layer currently covers Türkiye.

CountryStateCity.getAllDistricts(format?, options?);
CountryStateCity.getDistrictById(id);
CountryStateCity.getDistrictByPublicId(publicId);
CountryStateCity.getDistrictsByStateId(stateId, format?, options?);
CountryStateCity.getDistrictsByCountryCode(countryCode);
CountryStateCity.searchDistricts(query, stateId?);

const kadikoy = CountryStateCity.getDistrictByPublicId('csc:district:107863');
const istanbulDistricts = CountryStateCity.getDistrictsByStateId(2170);

officialDistrictCode remains null because the validation source does not publish an authoritative national district code.

Ranked location search

CountryStateCity.searchLocations(query, {
  countryCode?,
  stateCode?,
  stateId?,
  entityTypes?,
  typoTolerance?,
  limit?,
});

const matches = CountryStateCity.searchLocations('İstanbull', {
  countryCode: 'TR',
  entityTypes: ['state', 'city', 'district'],
  typoTolerance: true,
  limit: 10,
});

Each result carries its canonical public ID, score, match reason, parent context, matched alias, language, source, and validity metadata. See Multilingual location search.

Nearest centres

CountryStateCity.nearestCenters(point, options?);
CountryStateCity.nearestCentersBatch(points, options?);

const nearest = CountryStateCity.nearestCenters(
  { latitude: 40.9811, longitude: 29.0651 },
  {
    countryCode: 'TR',
    entityTypes: ['state', 'city', 'district'],
    limitPerType: 2,
    maxDistanceKm: 100,
  }
);

const batch = CountryStateCity.nearestCentersBatch([
  { latitude: 40.9811, longitude: 29.0651 },
  { latitude: 39.9334, longitude: 32.8597 },
]);

The result contains the query, immutable dataVersion, distance in kilometres, entity data, and center-distance confidence metadata.

A nearest centre is not proof that a point lies inside an administrative area. Use polygon containment when jurisdictional membership is required.

Polygon containment

const index = new PolygonLookupIndex(featureCollection);
const result = index.locate({ latitude: 40.9811, longitude: 29.0651 });

const oneOff = locatePointInPolygons({ latitude: 40.9811, longitude: 29.0651 }, featureCollection);

Both APIs accept compatible GeoJSON Polygon/MultiPolygon feature collections. The result reports all matching feature properties, boundary status, confidence, and the point-in-polygon method. Versioned package coverage currently includes Türkiye admin-1/admin-2 only.

Timezones and lookup lists

CountryStateCity.getAllRegions();
CountryStateCity.getAllSubregions();
CountryStateCity.getAllTimezones();
CountryStateCity.getTimezoneOffset(zoneName, at?);
CountryStateCity.getAllCurrencies();

getTimezoneOffset() accepts a Date, ISO date string, or epoch number and observes the supplied IANA zone at that instant.

const offset = CountryStateCity.getTimezoneOffset('America/New_York', '2026-08-09T12:00:00Z');

Statistics and coverage

CountryStateCity.getStats();
CountryStateCity.getCoverageReport();
CountryStateCity.getCountryCoverage(countryCode);

getStats() returns current country, state, city, and district counts. Coverage methods distinguish available, missing, notApplicable, and unknown; see Data coverage.

Generic export

CountryStateCity.exportData(
  dataType, // 'countries' | 'states' | 'cities' | 'districts'
  format, // 'json' | 'csv' | 'xml' | 'yaml'
  options?
);

const countriesCsv = CountryStateCity.exportData('countries', 'csv');
const statesXml = CountryStateCity.exportData('states', 'xml');
const citiesYaml = CountryStateCity.exportData('cities', 'yaml');
const districtsJson = CountryStateCity.exportData('districts', 'json');

API reference