impulsivefps
/
EU-Utility
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
EU-Utility/docs/NEXUS_API_REFERENCE.md

17 KiB
Raw Blame History

Entropia Nexus API Reference

Complete technical documentation for the Entropia Nexus API

Version: 1.0
Last Updated: 2025-02-13
Base URL: https://api.entropianexus.com

Table of Contents

  1. Overview
  2. Authentication
  3. Base Configuration
  4. Entity Types
  5. Endpoints
  6. Request Parameters
  7. Response Formats
  8. Error Handling
  9. Rate Limits
  10. Usage Examples
  11. Plugin API Integration
  12. Field Name Conventions

Overview

The Entropia Nexus API provides programmatic access to game data from Entropia Universe. It supports:

  • 25+ entity types (items, mobs, locations, skills, etc.)
  • Full-text search with fuzzy matching
  • Market data for trading analysis
  • Detailed entity information with stats and properties

Quick Start

from core.nexus_api import get_nexus_api

# Get API instance
api = get_nexus_api()

# Search for items
results = api.search_items("ArMatrix")

# Get detailed info
details = api.get_item_details("armatrix_lp-35")

# Get market data
market = api.get_market_data("armatrix_lp-35")

Authentication

The Entropia Nexus API is public and requires no authentication for read operations.

Request Headers

Recommended headers for all requests:

User-Agent: EU-Utility/1.0 (Entropia Universe Utility Tool)
Accept: application/json
Accept-Encoding: gzip

Base Configuration

API Client Settings

Setting Value Description
BASE_URL https://api.entropianexus.com API endpoint
API_VERSION v1 Current API version
MAX_REQUESTS_PER_SECOND 5 Rate limit for requests
MIN_REQUEST_INTERVAL 0.2s Minimum time between requests
MAX_RETRIES 3 Automatic retry attempts
RETRY_DELAY 1.0s Base delay between retries
DEFAULT_CACHE_TTL 300s Default cache lifetime (5 min)

Entity Types

Supported Entity Types

The API supports 25+ entity types organized into categories:

Equipment & Items

Entity Type Endpoint Description
items /items General items and components
weapons /weapons Ranged and melee weapons
armors /armors Protective armor sets
enhancers /enhancers Weapon/armor enhancers

Tools & Professional

Entity Type Endpoint Description
medicaltools /medicaltools First Aid Packs, healing tools
finders /finders Mining finders/detectors
excavators /excavators Mining excavators
refiners /refiners Resource refiners

Crafting & Materials

Entity Type Endpoint Description
blueprints /blueprints Crafting recipes
materials /materials Raw materials, ores, enmatters

Creatures & Characters

Entity Type Endpoint Description
mobs /mobs Creatures, monsters, NPCs
pets /pets Tameable companion creatures

Locations & Places

Entity Type Endpoint Description
locations /locations Points of interest
teleporters /teleporters Teleporter locations
shops /shops Player shops
vendors /vendors NPC vendors
planets /planets Planet information
areas /areas Geographic regions

Other

Entity Type Endpoint Description
skills /skills Player skills and professions
vehicles /vehicles Ships, cars, mounts
decorations /decorations Estate decorations
furniture /furniture Estate furniture
storagecontainers /storagecontainers Storage boxes
strongboxes /strongboxes Loot strongboxes

Endpoints

Search Endpoints

Universal Search

GET /search?q={query}&limit={limit}&fuzzy={true|false}

Search across all entity types simultaneously.

Parameters:

  • q (required): Search query string
  • limit (optional): Maximum results (default: 20, max: 100)
  • fuzzy (optional): Enable fuzzy matching (default: false)

Response:

[
  {
    "id": "armatrix-lp-35",
    "name": "ArMatrix LP-35 (L)",
    "type": "Weapon",
    "category": "Laser Weapons",
    "icon_url": "https://..."
  }
]

Entity-Specific Search

GET /{entity-type}?q={query}&limit={limit}&fuzzy={true|false}

Search within a specific entity type.

Example:

GET /weapons?q=ArMatrix&limit=20&fuzzy=true

Item Endpoints

Get Item Details

GET /items/{item-id}

Retrieve detailed information about a specific item.

Response:

{
  "id": "armatrix-lp-35",
  "name": "ArMatrix LP-35 (L)",
  "description": "A powerful laser pistol...",
  "category": "Laser Weapons",
  "weight": 2.5,
  "tt_value": 120.0,
  "decay": 0.5,
  "ammo_consumption": 10,
  "damage": 45.0,
  "range": 45.0,
  "accuracy": 80.0,
  "durability": 10000,
  "requirements": {
    "level": 25,
    "profession": "Laser Sniper (Hit)"
  },
  "materials": [
    {"name": "Lysterium Ingot", "amount": 50}
  ]
}

Get Market Data

GET /items/{item-id}/market

Retrieve current market data for an item.

Response:

{
  "item_id": "armatrix-lp-35",
  "item_name": "ArMatrix LP-35 (L)",
  "current_markup": 115.5,
  "avg_markup_7d": 112.3,
  "avg_markup_30d": 113.8,
  "volume_24h": 150,
  "volume_7d": 1200,
  "buy_orders": [
    {"price": 138.6, "quantity": 5}
  ],
  "sell_orders": [
    {"price": 145.2, "quantity": 10}
  ],
  "last_updated": "2025-02-13T10:30:00Z"
}

Entity Detail Endpoints

All entity types support individual retrieval:

GET /{entity-type}/{entity-id}

Examples:

GET /mobs/atrox
GET /locations/fort-izzuk
GET /blueprints/armatrix-lp-35
GET /skills/rifle

Market Data Endpoints (www.entropianexus.com)

Note: These endpoints use the www. subdomain, not api.

Exchange Listings

GET https://www.entropianexus.com/api/market/exchange

Response:

{
  "categories": [
    {
      "name": "Weapons",
      "items": [
        {
          "id": "item-id",
          "name": "Item Name",
          "type": "Weapon",
          "buy": [{"price": 100.0, "quantity": 5}],
          "sell": [{"price": 110.0, "quantity": 3}]
        }
      ]
    }
  ]
}

Latest Prices

GET https://www.entropianexus.com/api/market/prices/latest?items={comma-separated-ids}

Parameters:

  • items: Comma-separated list of item IDs (max 100)

Request Parameters

Common Parameters

Parameter Type Default Description
q string - Search query
query string - Alternative search parameter
limit integer 20 Maximum results (max: 100)
fuzzy boolean false Enable fuzzy matching
type string - Filter by entity type

Filter Parameters

Parameter Type Description
category string Filter by category
min_level integer Minimum level requirement
max_level integer Maximum level requirement
planet string Filter by planet name

Pagination

Parameter Type Description
offset integer Skip N results
limit integer Return N results

Response Formats

Standard Response Structure

All API responses follow a consistent structure:

Search Result Item

{
  "id": "string",          // Unique identifier
  "name": "string",        // Display name
  "type": "string",        // Entity type
  "category": "string",    // Category/classification
  "icon_url": "string",    // URL to icon image (optional)
  // Type-specific fields below
}

Type-Specific Response Fields

Weapons

{
  "id": "weapon-id",
  "name": "Weapon Name",
  "damage": 45.0,          // Damage per shot
  "range": 45.0,           // Effective range in meters
  "attacks": 45,           // Attacks per minute
  "ammo_consumption": 10,  // Ammo per shot
  "accuracy": 80.0,        // Accuracy percentage
  "decay": 0.5,            // Decay per use (PED)
  "durability": 10000      // Durability points
}

Armors

{
  "id": "armor-id",
  "name": "Armor Name",
  "protection": 25.0,      // Protection value
  "durability": 5000,      // Durability points
  "weight": 5.0            // Weight in kg
}

Mobs

{
  "id": "mob-id",
  "name": "Mob Name",
  "hitpoints": 1000,       // HP
  "damage": 50.0,          // Damage range
  "threat": "Medium",      // Threat level
  "planet": "Calypso",
  "area": "Eastern Land
}

Locations

{
  "id": "loc-id",
  "name": "Location Name",
  "planet": "Calypso",
  "x": 12345.0,           // X coordinate
  "y": 67890.0,           // Y coordinate
  "type": "Outpost"
}

Blueprints

{
  "id": "bp-id",
  "name": "Blueprint Name",
  "qr": 100.0,            // Quality Rating max
  "click": 1000,          // Total clicks
  "materials": [...],     // Required materials
  "product": {...}        // Output item
}

Skills

{
  "id": "skill-id",
  "name": "Skill Name",
  "category": "Combat",   // Skill category
  "description": "..."
}

Error Handling

HTTP Status Codes

Code Meaning Description
200 OK Request successful
400 Bad Request Invalid parameters
404 Not Found Entity not found
429 Too Many Requests Rate limit exceeded
500 Server Error Internal server error
502 Bad Gateway Upstream error
503 Service Unavailable Temporarily unavailable

Error Response Format

{
  "error": "Error type",
  "message": "Human-readable description",
  "code": 404
}

Exception Types (Python Client)

class NexusAPIError(Exception):
    """Base exception for Nexus API errors."""
    pass

class RateLimitError(NexusAPIError):
    """Raised when rate limit is exceeded."""
    pass

Error Handling Example

from core.nexus_api import get_nexus_api, NexusAPIError, RateLimitError

api = get_nexus_api()

try:
    details = api.get_item_details("invalid-id")
except RateLimitError as e:
    print(f"Rate limited: {e}")
    # Wait and retry
except NexusAPIError as e:
    print(f"API error: {e}")
except Exception as e:
    print(f"Unexpected error: {e}")

Rate Limits

Limits by Endpoint Type

Endpoint Type Limit Window
General API 5 requests per second
Search 10 requests per minute
Market Data 60 requests per minute
Item Details 30 requests per minute

Rate Limit Headers

Responses include rate limit information:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 45
X-RateLimit-Reset: 1707832800

Handling Rate Limits

# The client automatically handles rate limiting
api = get_nexus_api()

# Built-in retry with exponential backoff
results = api.search_items("ArMatrix")  # Auto-retries on 429

Usage Examples

Basic Search

from core.nexus_api import get_nexus_api

api = get_nexus_api()

# Search for items
items = api.search_items("ArMatrix", limit=20)
for item in items:
    print(f"{item.name} ({item.type})")

# Search for mobs
mobs = api.search_mobs("Atrox")
for mob in mobs:
    print(f"{mob.name} - HP: {mob.data.get('hitpoints')}")

Get Item Details

# Get detailed information
details = api.get_item_details("armatrix-lp-35")
if details:
    print(f"Name: {details.name}")
    print(f"TT Value: {details.tt_value} PED")
    print(f"Damage: {details.damage}")
    print(f"Range: {details.range}m")
    print(f"Decay: {details.decay} PED/use")

Market Analysis

# Get market data
market = api.get_market_data("armatrix-lp-35")
if market:
    print(f"Current markup: {market.current_markup:.1f}%")
    print(f"7-day average: {market.avg_markup_7d:.1f}%")
    print(f"24h Volume: {market.volume_24h}")
    
    # Check buy orders
    for order in market.buy_orders[:5]:
        print(f"Buy: {order['price']} PED x {order['quantity']}")

Batch Operations

# Get multiple items efficiently
item_ids = ["armatrix-lp-35", "armatrix-bp-25", "armatrix-sb-10"]
results = api.get_items_batch(item_ids)

for item_id, details in results.items():
    if details:
        print(f"{details.name}: {details.damage} dmg")

Universal Search (All Entity Types)

# Search across all types
results = api.search_all("Calypso", limit=30)
for result in results:
    print(f"{result.name} [{result.type}]")

Plugin API Integration

Accessing Nexus API from Plugins

Plugins access the Nexus API through the PluginAPI:

from plugins.base_plugin import BasePlugin

class MyPlugin(BasePlugin):
    def search_item(self, query):
        # Use the built-in nexus_search method
        results = self.nexus_search(query, entity_type="items")
        return results
    
    def get_item_info(self, item_id):
        # Get item details
        details = self.nexus_get_item_details(item_id)
        return details
    
    def check_market(self, item_id):
        # Get market data
        market = self.nexus_get_market_data(item_id)
        return market

Available Plugin Methods

Method Description
nexus_search(query, entity_type) Search for entities
nexus_get_item_details(item_id) Get item details
nexus_get_market_data(item_id) Get market data

Entity Types for Plugins

# Valid entity types for nexus_search()
entity_types = [
    "items", "weapons", "armors", "blueprints", "mobs",
    "locations", "skills", "materials", "enhancers",
    "medicaltools", "finders", "excavators", "refiners",
    "vehicles", "pets", "decorations", "furniture",
    "storagecontainers", "strongboxes", "teleporters",
    "shops", "vendors", "planets", "areas"
]

Plugin Example: Weapon Finder

from plugins.base_plugin import BasePlugin

class WeaponFinderPlugin(BasePlugin):
    name = "Weapon Finder"
    
    def find_weapons_by_damage(self, min_damage):
        """Find all weapons with minimum damage."""
        # Search for weapons
        results = self.nexus_search("", entity_type="weapons")
        
        weapons = []
        for weapon in results:
            details = self.nexus_get_item_details(weapon.id)
            if details and details.damage >= min_damage:
                weapons.append(details)
        
        return sorted(weapons, key=lambda w: w.damage, reverse=True)

Field Name Conventions

Important: Dual Naming Conventions

The API may return field names in either format:

  • snake_case: item_id, tt_value, current_markup
  • PascalCase: ItemId, TTValue, CurrentMarkup

Handling Both Formats

# Safe field access pattern
def get_field(data, *names, default=None):
    """Get field value trying multiple name variants."""
    for name in names:
        if name in data:
            return data[name]
    return default

# Usage
name = get_field(item, 'name', 'Name')
tt_value = get_field(item, 'tt_value', 'TTValue', 'TtValue')
damage = get_field(item, 'damage', 'Damage')

Common Field Mappings

Concept snake_case PascalCase
ID id Id
Name name Name
Type type Type
Category category Category
TT Value tt_value TTValue
Damage damage Damage
Range range Range
Decay decay Decay
Weight weight Weight
Hitpoints hitpoints Hitpoints
Level level Level
Description description Description

Data Classes Reference

SearchResult

@dataclass
class SearchResult:
    id: str              # Entity ID
    name: str            # Display name
    type: str            # Entity type
    category: str        # Category (optional)
    icon_url: str        # Icon URL (optional)
    data: dict           # Raw response data

ItemDetails

@dataclass
class ItemDetails:
    id: str
    name: str
    description: str
    category: str
    weight: float
    tt_value: float
    decay: float
    ammo_consumption: int
    damage: float
    range: float
    accuracy: float
    durability: int
    requirements: dict
    materials: list
    raw_data: dict

MarketData

@dataclass
class MarketData:
    item_id: str
    item_name: str
    current_markup: float
    avg_markup_7d: float
    avg_markup_30d: float
    volume_24h: int
    volume_7d: int
    buy_orders: list
    sell_orders: list
    last_updated: datetime
    raw_data: dict

Changelog

v1.0 (2025-02-13)

  • Initial complete API documentation
  • Documented all 25+ entity types
  • Added field naming convention notes
  • Added Plugin API integration examples

Related Files