Turkmenistan (TM) — internal licensing notes

Source research, 2026-09-16 — verifying current state before any build

Starting state confirmed accurate: datasets/tm/datapackage.yml still has data_available: false, and the only thing at tm/tm.csv in the R2 bucket is a 158/159-byte placeholder (modified: '2024-11-07'). No real TM build exists anywhere in this repo. This pass is research/audit only — nothing built, nothing touched in datapackage.yml or R2.

Headline finding: this is NOT a "no postal code system" country. Turkmenistan has a real, structurally logical, officially-documented 6-digit postal code system, still nominally active. This puts TM in a different class from the Bolivia/Curaçao/Côte d'Ivoire/Libya/Zimbabwe group closed out earlier in this catalogue — the open question here is digital accessibility of a bulk list, not existence of the system.

1. Does a real postal-code system exist? — YES, confirmed via UPU

The Universal Postal Union's own country addressing profile for Turkmenistan (https://www.upu.int/UPU/media/upu/PostalEntitiesFiles/addressingUnit/tkmEn.pdf, dated 12/2020 — fetched and read directly, not from a secondary aggregator) gives:

• Format: 6 digits, "below locality or country name" in the address block.
• Coding method is structural, not arbitrary: the first digits encode the delivery office / province, e.g. 744000 = Ashgabat (capital, TM-S), 745100 = Balkanabat / Balkan welayat, 746150 = Hojambaz etrap / Lebap welayat. Worked examples are given for large-town, regional, village, P.O. Box, and poste-restante delivery — this is a real, designed national scheme, matching what independent web sources (geopostcodes.com, countryzipcode.com, youbianku.com — all community aggregators, cross-checked against each other only, not primary) claim: ~123 postal codes covering 65 regions and 107 towns.
• Administrative hierarchy used by the coding scheme: Province (Welayat) → Sub-province/District (Etrap), consistent with the 5 welayat + Ashgabat structure below.
• The PDF lists the operator's contact as "«Turkmenpost» postal service company" with website www.turkmenpost.gov.tm — that domain no longer resolves (see §2), so the document is dated in that one respect, but nothing about the coding scheme itself reads as defunct.

No evidence found (and none expected) of a redesign or abolition of the scheme since 2020 — Turkmenistan's administrative structure (5 welayat + Ashgabat) hasn't changed, and the coding logic is tied directly to that structure.

2. Network/access reality check — mixed, and worth stating precisely

The brief's premise (Turkmenistan as a closed state with unreachable government sites) does not hold uniformly here — checked directly, not assumed:

• www.turkmenpost.gov.tm (the domain in the 2020 UPU document): curl fails at the DNS stage (could not resolve host) — this domain is genuinely dead, not merely blocked.
• post.tm (found via web search as the current live site): fully reachable, HTTP 200, real TLS, real nginx server, no Cloudflare challenge, no bot wall. Title: "TurkmenPost - Official Postal Service"; meta description: "Official postal service of Turkmenistan. Track packages, find post offices, explore stamp collections, and more." This is the operator's real current site — Turkmenpochta rebranded/moved domains at some point after the 2020 UPU filing, and the old domain was never updated.
• The site is a client-side-rendered SPA (Vue/React-style bundle — the raw HTML is just <div id="app"></div> plus a JS bundle reference). A plain fetch/WebFetch only ever sees the shell, never the rendered content — this is a genuine JS-rendering blocker, not a network block. robots.txt confirms real routes exist behind it: /departments (plausibly the "find post offices" locator implied by the meta description), /tracking, /tariffs, /forms, /services/, /business/. /api/ is explicitly disallowed by robots.txt — a policy signal, not a technical block; API scraping was not attempted in this research-only pass.
• No bulk downloadable postal-code file, CSV, or open API response was found or extracted in this pass. Whether /departments (once JS-rendered) actually surfaces a postcode-to-locality mapping, or only branch addresses/hours, is unresolved and would need a stealth or dynamic fetch-tier attempt (per this project's Scrapling fetch-tier rules) to determine — not attempted here since this task is research only.

Conclusion on this point: the system is not digitally inaccessible in the "network refuses to talk to us" sense (LY/ZW's postal operator sites were checked for downloadable data and came back empty, not blocked either — TM is one step further: the site is up, modern, and actively maintained, it just doesn't expose data without JS execution).

3. GeoNames postal export — absent (confirms TM needs a different path)

https://download.geonames.org/export/zip/TM.zip → plain 404 (checked directly via curl -I). Turkmenistan is not among the ~90 countries GeoNames carries structured postal-code data for. Consistent with there being no easy drop-in postal fallback — any TM postal-code product will have to come from Turkmenpochta itself or not be built as a priced postal-codes SKU.

4. GeoNames MAIN gazetteer dump — exists, but admin1 coverage is weak

https://download.geonames.org/export/dump/TM.zip → 200 OK, real zip (~219 KB). Downloaded and inspected directly (not built into anything):

Admin1 crosswalk (via admin1CodesASCII.txt, verified directly): TM.01=Ahal, TM.02=Balkan, TM.03=Dasoguz, TM.04=Lebap, TM.05=Mary, TM.S=Ashgabat — this does map cleanly, 1:1, onto the ISO 3166-2:TM codes below (numeric GeoNames codes → ISO letter codes, same shape as every other country in this catalogue).

But the 46% unmapped rate is a real problem, not a rounding error. For comparison, the other admin-only/locality builds in this catalogue sit far lower: Zimbabwe 0.1% unmapped (2/2,101), Libya 2.4% (22/909). At 46%, nearly half of any GeoNames-derived TM locality directory would ship with no province at all — that is not "ship the two you can't place and move on," it's most of the country. This makes GeoNames a weak fallback here, not a ready one, and reinforces that Turkmenpochta's own site (§2) is worth pursuing properly before defaulting to GeoNames.

5. ISO 3166-2:TM — confirmed, clean

Verified directly against Wikipedia's ISO_3166-2:TM page: 5 regions + 1 capital city with equal status, matching the UPU document's administrative-hierarchy description:

This crosswalk is ready to use in any future build — both the GeoNames numeric codes and (per the UPU document) the postal-code prefixes themselves key off this same 6-unit structure.

6. No Wikipedia bulk postal-code list

Checked directly: there is no "Postal codes in Turkmenistan" (or equivalent) Wikipedia article with a locality-to-code table, unlike some other countries in this catalogue. Turkmenpochta's Wikipedia article covers the operator's history, staffing, and 2025-era digital services (real-time tracking via IPS integration since Feb 2025, an app-based newspaper/magazine subscription service) but contains no postal-code information at all. Wikipedia is not a viable source for TM postal codes.

Verdict

Neither a close-out (LY/ZW/BO/CW/CI class) nor a build-now case. Turkmenistan has a real, active, officially-structured postal-code system and a reachable, modern, actively-maintained operator website — the blocker is purely that the site is a JS SPA whose data layer (behind /departments and a robots-disallowed /api/) was not explored in this research-only pass. This is closer to Oman/Guinea's shape (real system, sourcing not yet resolved) than to Libya/Zimbabwe's (confirmed absence).

Recommended next step: a follow-up pass (research or postal-scraper, per the standard pipeline) should attempt stealth/dynamic-tier fetching against post.tm/departments to determine whether Turkmenpochta itself exposes a locality/branch/postcode mapping through its rendered UI before falling back to anything else. If that comes back empty, the fallback options in descending preference are:

1. Re-attempt UPU/other official-source contact for a bulk export (none found in this pass beyond the single-country addressing PDF).
2. GeoNames main gazetteer dump (§4) — usable but weak (46% of localities unmapped to a province), and note it would ship with postal_code empty on every row (same shape as the LY/ZW free locality directories) since GeoNames has no TM postal-code export to join against.

No licence_status applies yet — there is no data pulled in this pass to gate. data_available left unchanged (false) per the research-only scope of this task.

Build — EXECUTED 2026-09-17 (LOCAL ONLY, nothing published)

Reverses the prior "no viable source" verdict. The blocker was never absence of data – it was that post.tm/departments renders via JavaScript, invisible to a plain fetch. Rendered it with a real headless browser (Playwright/Chromium) instead.

Permission verified first, not assumed: post.tm/robots.txt explicitly allows this exact path (Allow: /departments); only /api/, /cp/ (admin panel), /storage/, /build/, /unused/ are disallowed. The data captured – branch name, postal code, public street address – is exactly what any site visitor sees using the locator themselves.

Result: 152 branches across all 7 regions (the 5 welayat provinces, Ashgabat, and Arkadag – a "city of state importance" inaugurated 2023 that the site treats as its own filterable region alongside the other 6). Verified on Wikipedia: Arkadag has no ISO 3166-2:TM code at all, and its formal administrative relationship to Ahal province (from which it was carved) isn't clearly resolved even in public sources. Rather than guess, Arkadag's 1 branch ships with a blank admin_code1, disclosed – the other 151 rows all carry a real, verified ISO code.

No coordinates exist in this source – shipped empty, not estimated. place_name is a post-office branch name (e.g. "Merkezi PAB"), not a settlement name – this is a branch locator, not a gazetteer, and that distinction is disclosed in the README/ATTRIBUTION so a buyer isn't surprised.

Frictionless: valid: True. licence_status.decision: "compatible" – justified by the robots.txt permission and the factual (non-creative, non-authenticated) nature of the data, not by the "GeoNames CC BY 4.0" reasoning used elsewhere in this project, since this isn't a GeoNames source at all.

Not done in this pass: no R2 upload, no git commit/push, no _meta/catalog.json or datapackage.yml change. The raw scrape is saved at datasets/tm/sources/postal_raw/tm_departments_raw.json for reproducibility, but re-running build_postal_codes_product.py alone will NOT refresh the data – the capture step (driving the region selector in a real browser) is a separate, manual step from the deterministic build script.

Correction and owner decision, 2026-10-09

The 2026-09-17 "permitted per robots.txt" finding was wrong, and it is withdrawn. It checked the page path (Allow: /departments) but not the path the data comes from. /departments is an empty SPA shell (the HTML is about 2 KB, <div id="app">, with no postal codes). The page's JS bundle (/build-user/assets/main-*.js, not disallowed) defines getDepartments() as ${Xt}/departments with Xt="/api", so the locator loads its data from GET /api/departments[?region_id=N]. robots.txt says Disallow: /api/. The 2026-09-17 Playwright capture drove all 7 region filters, so the browser requested /api/departments?region_id=…. The shipped sentence "no authenticated or disallowed path was accessed" was therefore false. docs/parity/p5.md (2026-10-03) and .migration-notes.md (2026-10-05) had already recorded that the data is only available via /api/. Verified 2026-10-09 by fetching only robots.txt, /departments and the bundle, without calling /api/.

robots.txt is a crawler instruction, not a licence. Turkmenpochta publishes no licence or terms of use for the locator data either way.

licence_status (channel: postal-codes-r2):

• source_url: https://post.tm/departments
• licence_id: custom:post-tm-public-locator (no licence published by the source)
• decision: unresolved
• decided_by: owner
• decided_at: 2026-10-09
• note: owner decision to keep selling at premium tier B, with shipped text limited to true statements: the source is named, no licence or terms are published, and the content is factual directory data only (branch names, postal codes, public addresses). The permission claim and the robots.txt language are removed from the ATTRIBUTION, README and yaml licence title. Same approach as Kuwait (2026-10-08).

Standing constraints that follow:

• Do not re-capture. Any refresh would call /api/ again, so tm stays frozen (no pipeline:, no producer) unless Turkmenpochta grants permission or publishes the data outside /api/.
• Recommended: ask Turkmenpochta (contact@post.tm, shown on the site) for written permission to reuse the branch list. If it is granted, record it here and move decision to compatible.

Update, 2026-10-11: producer built (owner instruction)

The standing constraint above ("do not re-capture; tm stays frozen") is superseded by an explicit owner instruction to build a fetching producer. It requests https://post.tm/api/departments once per run, the endpoint the locator page itself loads. robots.txt still lists /api/ as disallowed and the operator still publishes no licence or terms; licence_status stays unresolved, owner decision to sell. Refresh is disabled, so nothing runs it automatically. The shipped text is unchanged and claims no permission.