langchain-apogeoapi

LangChain tools and toolkit for ApogeoAPI — IP geolocation, countries, states, cities, and real-time exchange rates.

Installation

pip install langchain-apogeoapi

Requirements

• Python 3.9+
• A free ApogeoAPI key — sign up at apogeoapi.com
• langchain-core>=0.1.0

Quick Start — Toolkit with a LangChain Agent

from langchain_apogeoapi import ApogeoAPIToolkit
from langchain_openai import ChatOpenAI
from langchain.agents import create_tool_calling_agent, AgentExecutor
from langchain_core.prompts import ChatPromptTemplate

# Initialize the toolkit
toolkit = ApogeoAPIToolkit(api_key="your-apogeoapi-key")
tools = toolkit.get_tools()

# Set up an LLM and agent
llm = ChatOpenAI(model="gpt-4o", temperature=0)
prompt = ChatPromptTemplate.from_messages([
    ("system", "You are a helpful geographic assistant. Use the available tools to answer questions about countries, cities, and IP addresses."),
    ("human", "{input}"),
    ("placeholder", "{agent_scratchpad}"),
])

agent = create_tool_calling_agent(llm, tools, prompt)
executor = AgentExecutor(agent=agent, tools=tools, verbose=True)

# Ask geographic questions
result = executor.invoke({"input": "What is the capital of Japan and what is the current USD/JPY exchange rate?"})
print(result["output"])

result = executor.invoke({"input": "Where is the IP address 8.8.8.8 located?"})
print(result["output"])

Individual Tool Usage

You can also use each tool directly without an agent:

from langchain_apogeoapi import (
    GetCountryTool,
    GeolocateIPTool,
    GetCurrencyRateTool,
    ListCountriesTool,
    SearchCountriesTool,
    GetStatesTool,
    GetCitiesTool,
    GlobalSearchTool,
)

api_key = "your-apogeoapi-key"

# Get country details
country_tool = GetCountryTool(api_key=api_key)
print(country_tool.run("DE"))  # Germany by ISO2 code
print(country_tool.run("JPN"))  # Japan by ISO3 code

# Geolocate an IP address
ip_tool = GeolocateIPTool(api_key=api_key)
print(ip_tool.run("8.8.8.8"))

# Get exchange rate
rate_tool = GetCurrencyRateTool(api_key=api_key)
print(rate_tool.run("EUR"))

# List all countries in a region
list_tool = ListCountriesTool(api_key=api_key)
print(list_tool.run("Europe"))

# Search countries by name
search_tool = SearchCountriesTool(api_key=api_key)
print(search_tool.run("united"))

# Get states/provinces
states_tool = GetStatesTool(api_key=api_key)
print(states_tool.run("US"))

# Get cities
cities_tool = GetCitiesTool(api_key=api_key)
print(cities_tool.run({"country_code": "US", "state": "California", "limit": 10}))

# Global search across all data types
global_tool = GlobalSearchTool(api_key=api_key)
print(global_tool.run("Paris"))

Available Tools

Tool name	Class	Description
apogeoapi_get_country	GetCountryTool	Get full country details by ISO2 or ISO3 code
apogeoapi_list_countries	ListCountriesTool	List all countries, optionally filtered by region
apogeoapi_search_countries	SearchCountriesTool	Search countries by name
apogeoapi_get_states	GetStatesTool	Get states/provinces for a country
apogeoapi_get_cities	GetCitiesTool	Get cities for a country, optionally filtered by state
apogeoapi_get_currency_rate	GetCurrencyRateTool	Get USD exchange rate for a currency (e.g. EUR, JPY)
apogeoapi_geolocate_ip	GeolocateIPTool	Geolocate an IP — country, city, ISP, ASN, VPN detection
apogeoapi_global_search	GlobalSearchTool	Search across countries, cities, and currencies at once

Tool Details

GetCountryTool

Returns: name, ISO codes, capital, region, subregion, population, area, currency, languages, timezones, borders, calling code, flag URL.

tool = GetCountryTool(api_key=api_key)
result = tool.run("BR")  # Brazil

ListCountriesTool

Valid region values: Africa, Americas, Asia, Europe, Oceania. Leave empty for all countries.

tool = ListCountriesTool(api_key=api_key)
result = tool.run("Asia")

SearchCountriesTool

Fuzzy name matching — useful when you have a partial country name.

tool = SearchCountriesTool(api_key=api_key)
result = tool.run("nether")  # Returns Netherlands

GetStatesTool

Returns administrative divisions (states, provinces, territories) for any country.

tool = GetStatesTool(api_key=api_key)
result = tool.run("CA")  # Canadian provinces

GetCitiesTool

Accepts country_code, optional state, and optional limit (default 50).

tool = GetCitiesTool(api_key=api_key)
result = tool.run({"country_code": "MX", "state": "Jalisco", "limit": 20})

GetCurrencyRateTool

Returns the exchange rate against USD, currency name, symbol, and freshness timestamp.

tool = GetCurrencyRateTool(api_key=api_key)
result = tool.run("ARS")  # Argentine Peso

GeolocateIPTool

Returns country, region, city, timezone, latitude/longitude, ISP name, ASN, and proxy/VPN/Tor flags.

tool = GeolocateIPTool(api_key=api_key)
result = tool.run("1.1.1.1")

GlobalSearchTool

Searches across all data types simultaneously. Useful for open-ended geographic queries.

tool = GlobalSearchTool(api_key=api_key)
result = tool.run("London")

Getting an API Key

1. Sign up for free at apogeoapi.com
2. Navigate to the API Keys section in your dashboard
3. Create a new key and copy it
4. Free tier includes 1,000 requests/month — no credit card required

Full API documentation: api.apogeoapi.com/api/docs

License

MIT — see LICENSE file.