Location Data¶

2 endpoints for retrieving structured reference data about countries and currencies by ISO code.

Python SDK Examples¶

Get country information¶

country_info accepts a 2-letter ISO country code and returns capital, currency, languages, phone prefix, and flag emoji.

from toolkitapi import Geo

with Geo(api_key="tk_...") as geo:
    country = geo.country_info("DE")

    print(country["name"])          # "Germany"
    print(country["capital"])       # "Berlin"
    print(country["currency_code"]) # "EUR"
    print(country["languages"])     # ["German"]
    print(country["phone_prefix"])  # "+49"
    print(country["flag"])          # "🇩🇪"
    print(country["region"])        # "Europe"

Look up a list of countries¶

from toolkitapi import Geo

countries = ["US", "GB", "JP", "BR", "AU"]

with Geo(api_key="tk_...") as geo:
    for code in countries:
        info = geo.country_info(code)
        print(f"{info['flag']} {info['name']:20} | Capital: {info['capital']:18} | Currency: {info['currency_code']}")

Output:

🇺🇸 United States        | Capital: Washington D.C.  | Currency: USD
🇬🇧 United Kingdom       | Capital: London           | Currency: GBP
🇯🇵 Japan                | Capital: Tokyo            | Currency: JPY
🇧🇷 Brazil               | Capital: Brasília         | Currency: BRL
🇦🇺 Australia            | Capital: Canberra         | Currency: AUD

Enrich IP geolocation data with country details¶

Combine ip_lookup and country_info to add full country context to an IP lookup:

from toolkitapi import Geo

with Geo(api_key="tk_...") as geo:
    # Step 1 — geolocate the IP
    ip_data = geo.ip_lookup("203.0.113.42")
    country_code = ip_data["country_code"]  # e.g. "AU"

    # Step 2 — enrich with country details
    country_data = geo.country_info(country_code)

    print(f"Country: {country_data['flag']} {country_data['name']}")
    print(f"Capital: {country_data['capital']}")
    print(f"Languages: {', '.join(country_data['languages'])}")
    print(f"Currency: {country_data['currency_code']} ({country_data['currency_name']})")
    print(f"Phone prefix: {country_data['phone_prefix']}")

Get currency information¶

currency_info accepts a 3-letter ISO 4217 currency code and returns symbol, decimal places, and the countries that use it.

from toolkitapi import Geo

with Geo(api_key="tk_...") as geo:
    currency = geo.currency_info("EUR")

    print(currency["name"])          # "Euro"
    print(currency["symbol"])        # "€"
    print(currency["code"])          # "EUR"
    print(currency["decimals"])      # 2
    print(currency["countries"])     # ["AT", "BE", "CY", "DE", ...]

Format prices in local currency¶

from toolkitapi import Geo

def format_price(amount: float, currency_code: str) -> str:
    """Format an amount using the correct symbol and decimal places."""
    with Geo(api_key="tk_...") as geo:
        info = geo.currency_info(currency_code)

    symbol = info["symbol"]
    decimals = info["decimals"]
    return f"{symbol}{amount:,.{decimals}f}"

print(format_price(1234.5, "USD"))  # "$1,234.50"
print(format_price(1234.5, "JPY"))  # "¥1,235"  (0 decimals)
print(format_price(1234.5, "EUR"))  # "€1,234.50"

Resolve a country's currency from IP¶

from toolkitapi import Geo

def get_currency_for_ip(ip: str) -> dict:
    """Return the local currency for a given IP address."""
    with Geo(api_key="tk_...") as geo:
        ip_data = geo.ip_lookup(ip)
        country = geo.country_info(ip_data["country_code"])
        currency = geo.currency_info(country["currency_code"])
    return {
        "country": country["name"],
        "currency_code": currency["code"],
        "currency_name": currency["name"],
        "symbol": currency["symbol"],
    }

result = get_currency_for_ip("8.8.8.8")
print(result)
# {"country": "United States", "currency_code": "USD", "currency_name": "US Dollar", "symbol": "$"}

Response Fields¶

country-info response:

currency-info response: