# Ingress Intel Report

A command-line tool for fetching and analyzing game events from the Ingress Intel API.

## Features

- **Geographic Filtering**: Query events within a bounding box
- **Event Classification**: Automatic event type detection (portal captures, links, resonators, etc.)
- **Player Tracking**: Filter events by specific players
- **Timestamp Filtering**: Filter events by time range
- **Coordinate Extraction**: Extract portal locations from events

## Installation

```bash
# Using uv (recommended)
uv sync

# Using pip
pip install -r requirements.txt
```

## Configuration

Set your Ingress cookie as an environment variable:

```bash
export INGRESS_COOKIE="your_cookie_here"
```

Or hardcode it in [`main.py`](main.py:82) (not recommended).

## Usage

### Basic Usage

```bash
# Get all events in default area (Venice, Italy)
python main.py

# Show help
python main.py --help
```

### Command Line Options

| Option            | Type             | Default  | Description                                                                                                                                                                                                                               |
| ----------------- | ---------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--event-types`   | Multiple strings | None     | Filter by event types. Accepts one or more values from: `RESONATOR_DEPLOYED`, `RESONATOR_DESTROYED`, `PORTAL_CAPTURED`, `PORTAL_NEUTRALIZED`, `PORTAL_UNDER_ATTACK`, `LINK_CREATED`, `LINK_DESTROYED`, `CONTROL_FIELD_CREATED`, `UNKNOWN` |
| `--player-name`   | String           | None     | Filter events by a specific player name                                                                                                                                                                                                   |
| `--min-lat`       | Integer          | 45470259 | Minimum latitude (in microdegrees, E6 format)                                                                                                                                                                                             |
| `--min-lng`       | Integer          | 12244155 | Minimum longitude (in microdegrees, E6 format)                                                                                                                                                                                            |
| `--max-lat`       | Integer          | 45480370 | Maximum latitude (in microdegrees, E6 format)                                                                                                                                                                                             |
| `--max-lng`       | Integer          | 12298207 | Maximum longitude (in microdegrees, E6 format)                                                                                                                                                                                            |
| `--min-timestamp` | Timestamp        | -1       | Minimum timestamp (milliseconds since epoch or ISO 8601 format)                                                                                                                                                                           |
| `--max-timestamp` | Timestamp        | -1       | Maximum timestamp (milliseconds since epoch or ISO 8601 format)                                                                                                                                                                           |

### Timestamp Filtering

The `--min-timestamp` and `--max-timestamp` options support two formats:

**Format 1: Milliseconds (integer)**
```bash
python main.py --min-timestamp 1736659200000 --max-timestamp 1736745600000
```

**Format 2: ISO 8601 datetime string**
```bash
python main.py --min-timestamp "2026-01-12T00:00:00Z" --max-timestamp "2026-01-13T00:00:00Z"
```

**Examples:**

```bash
# Get events from last hour
python main.py --min-timestamp 1736659200000

# Get events for a specific day
python main.py --min-timestamp "2026-01-12T00:00:00Z" --max-timestamp "2026-01-13T00:00:00Z"

# Get events from a specific time onwards
python main.py --min-timestamp "2026-01-12T10:00:00Z"

# Get events up to a specific time
python main.py --max-timestamp "2026-01-12T12:00:00Z"
```

### Event Type Filtering

```bash
# Filter by single event type
python main.py --event-types PORTAL_CAPTURED

# Filter by multiple event types
python main.py --event-types PORTAL_CAPTURED LINK_CREATED CONTROL_FIELD_CREATED

# Filter by resonator events
python main.py --event-types RESONATOR_DEPLOYED RESONATOR_DESTROYED
```

### Player Filtering

```bash
# Filter by player name
python main.py --player-name Albicocca

# Combine with event type filter
python main.py --player-name Albicocca --event-types PORTAL_CAPTURED
```

### Geographic Filtering

Coordinates are in **E6 format** (microdegrees): multiply decimal degrees by 1,000,000.

```bash
# Custom geographic bounds
python main.py --min-lat 45470000 --max-lat 45480000 --min-lng 12240000 --max-lng 12300000
```

### Combining Filters

```bash
# Complex query with multiple filters
python main.py \
  --min-timestamp "2026-01-12T10:00:00Z" \
  --max-timestamp "2026-01-12T12:00:00Z" \
  --event-types PORTAL_CAPTURED LINK_CREATED \
  --player-name Albicocca \
  --min-lat 45470000 \
  --max-lat 45480000
```

## Event Types

| Event Type              | Description                        |
| ----------------------- | ---------------------------------- |
| `RESONATOR_DEPLOYED`    | Player deploys resonator on portal |
| `RESONATOR_DESTROYED`   | Resonator destroyed                |
| `PORTAL_CAPTURED`       | Portal captured by player          |
| `PORTAL_NEUTRALIZED`    | Portal neutralized                 |
| `PORTAL_UNDER_ATTACK`   | Portal being attacked              |
| `LINK_CREATED`          | Link created between portals       |
| `LINK_DESTROYED`        | Link destroyed                     |
| `CONTROL_FIELD_CREATED` | Control field created              |
| `UNKNOWN`               | Unrecognized event type            |

## Output Format

Events are printed in the following format:

```
[2026-01-12 10:28:27] [PORTAL_CAPTURED] Albicocca captured L' Arboreto - Coords: 45471652, 12274703
[2026-01-12 10:28:26] [LINK_CREATED] Albicocca linked from L' Arboreto to Parco San Giuliano - Coords: 45471652, 12274703
```

## Project Structure

```
ingress/
├── main.py           # CLI entry point
├── ingress.py        # API client
├── models.py         # Data models
├── pyproject.toml     # Project configuration
└── README.md         # This file
```

## Dependencies

- Python 3.13+
- requests 2.31.0+

## License

See project license file for details.