tmmaps

README

tm-maps

WGS84 (EPSG:4326) GeoJSON boundaries and geographic data for Turkmenistan, with a Go API for easy access.

Version: v0.1

GeoJSON

• data/geojson/turkmenistan-welayatlar.geojson — all welaýats in a single FeatureCollection
• data/geojson/turkmenistan-etraplar.geojson — available ADM2 district boundaries
• data/geojson/yerlesim-noktalari.geojson — 1,485 settlements with available coordinates
• data/regions.json — all 2,711 region and settlement records
• data/regions/*.json — records grouped by Ahal, Balkan, Daşoguz, Lebap, Mary, Aşgabat, and Arkadag
• data/regions/unassigned.json — 96 records that could not be assigned to a welaý
• data/geojson/welayatlar/ahal.geojson
• data/geojson/welayatlar/balkan.geojson
• data/geojson/welayatlar/dasoguz.geojson
• data/geojson/welayatlar/lebap.geojson
• data/geojson/welayatlar/mary.geojson

Each boundary feature contains:

• slug
• name_tm
• name_en
• iso_3166_2
• admin_level

GeoJSON coordinates follow the standard [longitude, latitude] order.

Go

Install:

go get github.com/turkmenos/tm-maps

Usage:

package main

import (
	"fmt"

	tmmaps "github.com/turkmenos/tm-maps"
)

func main() {
	all, err := tmmaps.All()
	if err != nil {
		panic(err)
	}

	ahal, err := tmmaps.Welaýat("ahal")
	if err != nil {
		panic(err)
	}

	fmt.Println(len(all))
	fmt.Println(len(ahal))
}

The geographic data is embedded in the Go package, so no external files or network requests are required at runtime.

Coordinate lookup

RegionAt returns the welaýat containing a latitude and longitude:

region, err := tmmaps.RegionAt(37.960077, 58.326063)
if err != nil {
	panic(err)
}
fmt.Println(region.NameTM) // Ahal

Invalid coordinates return ErrInvalidCoordinate. Coordinates outside the available boundaries return ErrRegionNotFound; both can be checked with errors.Is.

The parameters use (latitude, longitude) order. GeoJSON coordinates are converted internally from their standard [longitude, latitude] order.

Data Coverage

The administrative boundaries are sourced from the geoBoundaries TKM-ADM1-27578892 dataset and represent boundaries from 2007.

Aşgabat is not represented as a separate ADM1 polygon in the source dataset and appears within Ahal. Arkadag, established as a city in 2023, is also not represented separately because the geometry dataset predates its creation.

For this reason, v0.1 includes boundary geometries for the five welaýats:

• Ahal
• Balkan
• Daşoguz
• Lebap
• Mary

Aşgabat and Arkadag may still appear in the geographic/settlement datasets where data is available, but they do not have separate ADM1 boundary geometries in this release.

License

The source boundary dataset is released under the Public Domain.

See DATA_LICENSE.md for data licensing and attribution details.

Documentation

Overview

Package tmmaps provides Türkmenistan administrative boundary GeoJSON data.

Index

• Variables
• func Welaýat(name string) ([]byte, error)
• type Region
  • func Children(parentSlug string) ([]Region, error)
  • func FindRegion(slug string) (*Region, error)
  • func RegionAt(latitude, longitude float64) (*Region, error)
  • func Regions() ([]Region, error)
  • func Search(query string) ([]Region, error)

Variables

var (
	// ErrInvalidCoordinate indicates latitude or longitude outside its valid range.
	ErrInvalidCoordinate = errors.New("invalid coordinate")
	// ErrRegionNotFound indicates a coordinate outside the available welaýat boundaries.
	ErrRegionNotFound = errors.New("coordinate is outside available boundaries")
)

Functions

func Welaýat

func Welaýat(name string) ([]byte, error)

Types

type Region

type Region struct {
	Slug               string   `json:"slug"`
	NameTM             string   `json:"name_tm"`
	NameEN             string   `json:"name_en"`
	NameRU             string   `json:"name_ru"`
	Type               string   `json:"type"`
	ParentSlug         string   `json:"parent_slug"`
	Latitude           *float64 `json:"latitude"`
	Longitude          *float64 `json:"longitude"`
	VerificationStatus string   `json:"verification_status"`
}

func Children

func Children(parentSlug string) ([]Region, error)

func FindRegion

func FindRegion(slug string) (*Region, error)

func RegionAt

func RegionAt(latitude, longitude float64) (*Region, error)

RegionAt returns the welaýat containing latitude and longitude. Boundary points are treated as contained. The lookup is entirely offline.

func Regions

func Regions() ([]Region, error)

func Search

func Search(query string) ([]Region, error)