EVE ESI Integration Skill

Comprehensive guide for integrating EVE Online's official APIs into third-party applications.

Quick Reference

Critical Rules (CCP Terms of Service)

1. Always set User-Agent header with app name + contact email
2. Respect cache headers - Don't poll faster than Expires header
3. Error budget: 100 errors per 60 seconds → HTTP 420 ban
4. Never use ESI to discover structures/characters (bannable)
5. Rate limit: Prefer consistent slow traffic over spiky bursts

ESI Endpoints by Project Type

For Map/Navigation Apps (EVE_Starmap)

Public endpoints (no auth):

GET /universe/systems/                    → All 8,285 system IDs
GET /universe/systems/{system_id}/        → Position, security, stargates
GET /universe/stargates/{stargate_id}/    → Destination system (for connections)
GET /universe/constellations/{id}/        → System groupings
GET /universe/regions/                    → Region list
GET /route/{origin}/{destination}/        → Shortest path (flag=shortest|secure|insecure)
GET /universe/system_jumps/               → Live jump activity (heatmaps)
GET /universe/system_kills/               → Live kill activity (heatmaps)
GET /incursions/                          → Active incursions
GET /sovereignty/map/                     → Sovereignty data

Auth endpoints (SSO required):

GET /characters/{id}/location/            → esi-location.read_location.v1
POST /ui/autopilot/waypoint/              → esi-ui.write_waypoint.v1
GET /characters/{id}/assets/              → esi-assets.read_assets.v1

For Games/Visual Apps (EVE_Rebellion, EVE_Ships)

Image Server (no auth, no rate limit):

https://images.evetech.net/types/{type_id}/render?size=512    → Ship 3D render
https://images.evetech.net/types/{type_id}/icon?size=64       → Inventory icon
https://images.evetech.net/alliances/{id}/logo?size=128       → Alliance logo
https://images.evetech.net/corporations/{id}/logo?size=128    → Corp logo
https://images.evetech.net/characters/{id}/portrait?size=256  → Character portrait

Sizes: 32, 64, 128, 256, 512, 1024

Type info (for ship stats):

GET /universe/types/{type_id}/            → Name, description, dogma attributes
GET /universe/categories/{category_id}/   → Category info
GET /dogma/attributes/{attribute_id}/     → Attribute definitions

Common ship type IDs: Rifter=587, Tristan=593, Caracal=621, Drake=24690, Machariel=17738

For Overview/UI Tools

Client-interaction endpoints (auth required):

POST /ui/openwindow/information/          → Open info window
POST /ui/openwindow/marketdetails/        → Open market window
POST /ui/autopilot/waypoint/              → Set waypoint
GET /characters/{id}/skills/              → Character skills
GET /characters/{id}/ship/                → Current ship

Implementation Pattern

import httpx
from datetime import datetime

class ESIClient:
    BASE = "https://esi.evetech.net/latest"
    
    def __init__(self, app_name: str, contact_email: str):
        self.headers = {
            "User-Agent": f"{app_name}/1.0 ({contact_email})",
            "Accept": "application/json"
        }
        self._cache = {}
    
    async def get(self, endpoint: str, params: dict = None) -> dict:
        cache_key = f"{endpoint}:{params}"
        
        # Check cache
        if cache_key in self._cache:
            cached = self._cache[cache_key]
            if datetime.now() < cached["expires"]:
                return cached["data"]
        
        async with httpx.AsyncClient() as client:
            r = await client.get(
                f"{self.BASE}{endpoint}/",
                headers=self.headers,
                params=params
            )
            
            # Check error limit headers
            if "X-ESI-Error-Limit-Remain" in r.headers:
                remain = int(r.headers["X-ESI-Error-Limit-Remain"])
                if remain < 20:
                    print(f"⚠️ ESI error budget low: {remain} remaining")
            
            r.raise_for_status()
            
            # Cache based on Expires header
            if "Expires" in r.headers:
                expires = datetime.strptime(
                    r.headers["Expires"], 
                    "%a, %d %b %Y %H:%M:%S %Z"
                )
                self._cache[cache_key] = {
                    "data": r.json(),
                    "expires": expires
                }
            
            return r.json()

SSO Authentication Flow

For authenticated endpoints, see references/sso-flow.md.

Quick summary:

1. Register app at https://developers.eveonline.com/applications
2. OAuth2 Authorization Code flow
3. Token refresh via /v2/oauth/token
4. Include Authorization: Bearer {token} header

SDE (Static Data Export)

For offline/bulk data, use SDE instead of hitting ESI repeatedly:

• Official: https://developers.eveonline.com/resource/resources
• SQLite conversion: https://www.fuzzwork.co.uk/dump/
• Contains: All systems, stargates, types, attributes, coordinates

Recommended for:

• Initial map data load (8k+ systems)
• Ship/module attributes
• Industry recipes
• Anything that doesn't change between patches

Compliance Checklist

Run scripts/esi_compliance_check.py on any project to verify:

• User-Agent header set with contact info
• Cache headers respected
• Error limit headers monitored
• No discovery abuse patterns
• Rate limiting implemented
• Versioned endpoints used (/latest/ or /v{n}/)

Project-Specific Guidance

EVE_Rebellion Integration Points

Current: Procedural audio, data-driven enemies, no ESI Opportunities:

1. Ship renders from Image Server - Replace placeholder sprites
2. Type attributes from ESI - Real ship stats for enemy scaling
3. zkillboard API - Leaderboards, kill tracking

EVE_Starmap Integration Points

Current: Architecture planned, needs implementation Required:

1. SDE import - Bulk system/stargate data
2. Live layers - /universe/system_kills/, /universe/system_jumps/
3. Route API - /route/{origin}/{destination}/
4. SSO for location - Character position overlay

EVE_Ships Integration Points

Current: SVG assets Opportunities:

1. Image Server automation - Script to fetch all ship renders
2. Type metadata - Associate renders with ship stats
3. Category organization - Group by ship class from ESI

File References

• references/sso-flow.md - Complete SSO authentication guide
• references/endpoints-map.md - All map/navigation endpoints
• references/endpoints-character.md - Character-scoped endpoints
• references/image-server.md - Image URL patterns and sizes
• scripts/esi_compliance_check.py - Project compliance scanner
• scripts/fetch_ship_renders.py - Bulk image downloader
• scripts/sde_to_sqlite.py - SDE conversion helper