All Projects
Bot
Location Extractor Bot
A Telegram bot that provides instant access to global country, state, and city data with interactive inline pagination.
Role: Sole Developer
Problem Statement
Looking up geographic hierarchies (countries, their states, and respective cities) often requires querying databases or navigating web interfaces, which adds friction to a simple data retrieval task.
Target users: Developers, data analysts, and Telegram users needing quick geographic lookups without leaving their messaging app.
Project Walkthrough
I built the Location Extractor Bot to provide developers and users with a quick, accessible way to fetch geographic data—countries, states, and cities—directly from Telegram. The core problem it solves is reducing the friction of looking up location codes and hierarchies without needing a separate browser or database.
For the technical approach, I used Python with `python-telegram-bot` for handling asynchronous bot interactions, and integrated the external CountryStateCity API via a dedicated service class (`LocationService`) for clean separation of concerns. One of the interesting challenges was dealing with large datasets like the list of all countries, which would exceed Telegram's message limits. I solved this by implementing custom pagination using `InlineKeyboardMarkup`, making the data easy to navigate. I also included a lightweight Flask server to expose a `/send_command` endpoint, allowing the bot to be triggered by external applications.
The project is a clean demonstration of integrating third-party APIs with conversational interfaces. The modular architecture ensures that the bot logic, HTTP requests, and the web server remain decoupled.
Tech Stack
Languages
Frameworks
Cloud & Infrastructure
Dev Tools
Authentication
API Key (Telegram Token & CountryStateCity API Key)
Third-Party APIs & Integrations
Telegram Bot API
CountryStateCity API
System Architecture
Architecture Pattern
Service-Oriented Architecture (Modular)
Request Data Flow
Client (Telegram) -> Bot Command Handler -> LocationService -> CountryStateCity API -> JSON Response -> Bot Formats Message -> Client
Key Engineering Decisions
Decoupled the Telegram bot logic from the data-fetching logic by creating a dedicated `LocationService` class. Added a Flask web server to allow external applications to trigger bot messages via a POST webhook.
Database Design
N/A (Relies entirely on the external CountryStateCity API for geographic data)
Module Structure
Key Features & Implementation
Geographic Data Lookup
Users can fetch lists of countries, states by country code, and cities by state/country code.
How it was built
Implemented `/countries`, `/states`, and `/cities` Telegram commands that interface with the `LocationService` to fetch and format real-time data from the CountryStateCity API.
Interactive Pagination
Allows users to scroll through large lists of countries without flooding the chat.
How it was built
Built a custom pagination system using Telegram's `InlineKeyboardMarkup`. It calculates page slices and dynamically edits the message when 'Next' or 'Previous' inline buttons are clicked.
External Command API
An HTTP endpoint that allows external systems to send messages through the bot.
How it was built
Created a lightweight Flask server (`server.py`) exposing a `/send_command` POST route that takes a chat ID and command payload, forwarding it to the Telegram API.
Challenges & Engineering Decisions
Handling large datasets within Telegram's message size limits was a significant challenge. Returning all countries at once would result in poor user experience or failed requests. I solved this by implementing stateful inline pagination using Telegram's CallbackQueryHandlers. Additionally, ensuring the bot could run independently while still exposing an API for external triggers required configuring a separate Flask server script tailored for cloud deployment on Render.
API Documentation
API Route Namespaces