175 lines
6.9 KiB
Markdown
175 lines
6.9 KiB
Markdown
# 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.
|