EMTMadrid

A modern, asynchronous Python wrapper for the Madrid EMT (Empresa Municipal de Transportes) API, providing easy access to real-time public transportation data in Madrid, Spain.

Features

• Real-time bus arrival information
• Stop information and details
• Simple and intuitive interface
• Asynchronous API client using aiohttp
• Type hints for better development experience
• Modern Python 3.13+ codebase
• Comprehensive test suite
• Code quality tools pre-configured

Installation

Using pip

Install the package from PyPI:

pip install emt-madrid

Development Setup

1. Clone the repository:

   git clone https://github.com/fermartv/EMTMadrid.git
   cd EMTMadrid
   

2. Set up the development environment:

   make local-setup
   source .venv/bin/activate
   

   This will:

   • Install Python 3.13.2 using uv
   • Set up pre-commit hooks
   • Install all dependencies
   • Activate the virtual environment

Usage

Prerequisites

1. Python 3.13.2 or higher
2. An active EMT MobilityLabs account

Authentication

To use the EMT MobilityLabs API, you need to register on their official website. After registration:

1. Complete the email verification process
2. Note your login credentials (email and password)

Basic Example

import asyncio
from aiohttp import ClientSession
from emt_madrid import EMTClient

async def main():
    # Replace these with your actual credentials
    EMAIL = "your-email@example.com"
    PASSWORD = "your-password"
    STOP_ID = "72"  # Example stop ID

    async with ClientSession() as session:
        # Create EMT client
        emt_client = EMTClient(
            email=EMAIL,
            password=PASSWORD,
            stop_id=STOP_ID,
            session=session,
        )

        # Fetch stop information and arrivals
        arrivals = await emt_client.get_arrivals()
        
        # Get and display the data
        print("Stop Information:", arrivals)

if __name__ == "__main__":
    asyncio.run(main())

More examples can be found in the example directory. Run them with:

make run-example

Available Methods

EMTClient

• get_arrivals(): Fetches and updates stop information including bus arrivals with coordinates
• get_stop_info(): Returns the stop information

Data Models

BusArrival

Real-time bus arrival information including:

• line: Bus line number
• bus_id: Unique bus identifier
• destination: Bus destination
• coordinates: Bus GPS coordinates [longitude, latitude]
• estimate_arrive_sec: Estimated arrival time in seconds
• distance_bus: Distance to stop in meters
• is_head: Whether this is the head bus
• deviation: Route deviation in seconds
• position_type_bus: Bus position type indicator

Stop

Bus stop information including:

• stop_id: Unique stop identifier
• stop_name: Stop name
• stop_address: Stop address
• stop_coordinates: Stop GPS coordinates [longitude, latitude]
• stop_lines: List of Line objects serving this stop
• bus_arrivals: List of BusArrival objects with real-time arrival data and coordinates

Development

Project Structure

EMTMadrid/
├── emt_madrid/      # Main package source code
├── tests/           # Test files
├── example/         # Example scripts
├── pyproject.toml   # Project configuration
└── Makefile         # Development commands

Available Commands

• make install: Install all dependencies
• make update: Update dependencies
• make test: Run tests
• make test-coverage: Run tests with coverage report
• make check-typing: Run static type checking
• make check-lint: Check code style
• make check-format: Check code formatting
• make lint: Fix code style issues
• make format: Format code
• make pre-commit: Run all checks and tests (used in CI)
• make run-example: Run the basic example

Adding Dependencies

• For development dependencies:

  make add-dev-package package=package-name
  

• For production dependencies:

  make add-package package=package-name
  

Contributing

Contributions are welcome! Please follow these steps:

1. Fork the repository
2. Create your feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

Before submitting your PR, please make sure to:

• Run all tests with make test
• Ensure code style is consistent with make lint and make format
• Update the documentation if needed

License

This project is licensed under the GPLv3 - see the LICENSE file for details.

Acknowledgments

• EMT Madrid MobilityLabs for providing the API
• API Documentation