worlddatax 1.0.0

Comprehensive offline datasets for global country, currency, and geography metadata.

worlddatax

worlddatax is a production-ready Python package that ships an up-to-date, structured snapshot of worldwide geographic and country metadata. It exposes a simple, beginner-friendly API that reads from packaged JSON datasets covering every UN-recognised sovereign state.

Features

• 195 countries with ISO codes, capitals, continents, currencies, and international dialling prefixes
• Deep-dives for key markets with state, province, and city coverage
• Clean Python functions that never print or raise on missing records—receiving None or empty collections instead
• Zero runtime network access; all data is bundled in JSON and loaded on demand with caching

Installation

Install the library directly from a source checkout or from PyPI (when published):

pip install worlddatax

For local development use:

pip install -e .

Quick start

from worlddatax import (
		get_all_countries,
		get_country_by_iso,
		get_countries_by_continent,
		get_states,
		get_cities,
		get_currency,
		get_phone_code,
)

india = get_country_by_iso("IND")
asia = get_countries_by_continent("Asia")
states = get_states("United States")
california_cities = get_cities("United States", "California")
yen = get_currency("Japan")
usa_codes = get_phone_code("United States")

print(india["capital"])          # New Delhi
print(len(asia))                  # 46
print(states[:3])                 # ['Alabama', 'Alaska', 'Arizona']
print(california_cities)          # ['Los Angeles', 'San Francisco']
print(yen)                        # {'code': 'JPY', 'name': 'Japanese yen', 'symbol': '¥'}
print(usa_codes)                  # ['+1']

Packaged data

• Countries: names, ISO-2, ISO-3, capitals, continents, currency metadata, international calling prefixes
• States and provinces: complete lists for Australia, Brazil, Canada, China, France, Germany, India, and the United States
• Cities: curated coverage for major regions within the above countries
• Currencies: code, display name, and symbol for every currency referenced by the dataset
• Continents: continent-to-country mappings for simplified grouping

Datasets are fetched from the public REST Countries service during packaging and bundled into JSON files inside the distribution. All files are UTF-8 encoded and ship with the wheel, ensuring offline availability.

Project layout

worlddatax/
	worlddatax/           # Package modules
	data/                 # JSON datasets bundled with the wheel
	tests/                # Automated contract checks

Testing

Run the included test suite with pytest:

pytest

License

worlddatax is released under the MIT License. See LICENSE for details.