The Complete Guide to Grepolis Database: Understanding Game Data, APIs, and Tools

Introduction

Grepolis, the popular browser-based strategy game by InnoGames, generates vast amounts of data across its numerous game worlds. For serious players, alliance leaders, and developers, understanding the Grepolis database system is crucial for gaining competitive advantages and creating useful tools. This comprehensive guide explores everything you need to know about accessing, interpreting, and utilizing Grepolis game data.

---

Table of Contents

1. What is the Grepolis Database?
2. Types of Game Data Available
3. How to Access Grepolis Data Files
4. Understanding Data File Structures
5. Building Tools with Grepolis Data
6. Grepolis APIs and Third-Party Tools
7. Best Practices for Data Usage
8. Common Use Cases
9. Frequently Asked Questions (FAQs)
10. Conclusion

---

What is the Grepolis Database?

The term Grepolis database refers to the collection of public game data that InnoGames makes available for each game world. This isn’t a single downloadable database file, but rather a systematic arrangement of compressed text files and APIs containing current game state information.

Key Features of Grepolis Game Data:

• Public Accessibility: Available to all players without authentication
• Regular Updates: Refreshed approximately every hour
• World-Specific: Each game world maintains its own dataset
• Comprehensive Coverage: Includes player statistics, alliance information, town data, and historical records

---

Types of Game Data Available

Grepolis provides multiple data files, each serving a specific purpose. Here’s a comprehensive breakdown of available data sources:

Core Data Files

File Name	Description	Update Frequency
players.txt.gz	Complete player roster with rankings	Hourly
alliances.txt.gz	Alliance information and rankings	Hourly
towns.txt.gz	Detailed town data with coordinates	Hourly
islands.txt.gz	Island configurations and types	Daily
conquers.txt.gz	Historical conquest records	Real-time

Statistical Data Files

File Name	Content	Purpose
player_kills_all.txt.gz	Total battle points (players)	Combat rankings
player_kills_att.txt.gz	Attack battle points	Offensive strength
player_kills_def.txt.gz	Defense battle points	Defensive capability
alliance_kills_all.txt.gz	Alliance battle rankings	Team combat stats

Static Game Data

File Name	Format	Description
units.json.gz	JSON	Unit specifications and attributes
buildings.json.gz	JSON	Building requirements and effects
research.json.gz	JSON	Technology tree information
culture.json.gz	JSON	Cultural level requirements

---

How to Access Grepolis Data Files

Basic URL Structure

All Grepolis data files follow a consistent URL pattern:

text

http://[world].grepolis.com/data/[filename]

For example:

• http://en1.grepolis.com/data/players.txt.gz
• http://de1.grepolis.com/data/alliances.txt.gz
• http://us1.grepolis.com/data/towns.txt.gz

Download Methods

Method 1: Direct Browser Download

Simply enter the URL in your browser to download compressed files.

Method 2: Using Command Line (wget)

bash

# Download player data from world en1
wget http://en1.grepolis.com/data/players.txt.gz

# Decompress the file
gunzip players.txt.gz

# View the contents
head players.txt

Method 3: Programmatic Access (Python)

python

import gzip
import urllib.request
import csv

def download_grepolis_data(world, data_type):
    url = f"http://{world}.grepolis.com/data/{data_type}.txt.gz"
    response = urllib.request.urlopen(url)
    with gzip.GzipFile(fileobj=response) as data_file:
        reader = csv.reader(data_file.read().decode('utf-8').splitlines())
        return list(reader)

# Example: Get players from world en1
players = download_grepolis_data('en1', 'players')

---

Understanding Data File Structures

Players File Format

text

player_id,name,alliance_id,points,rank,num_towns

Example:

text

1,AlexTheGreat,101,25000,1,8
2,Spartacus,101,23450,2,7
3,Leonidas,102,22000,3,6

Alliances File Format

text

alliance_id,name,points,rank,num_towns,num_members

Example:

text

101,GreekGods,1250000,1,45,25
102,RomanEmpire,980000,2,38,22

Towns File Format

text

town_id,player_id,name,island_x,island_y,slot_on_island,points

Example:

text

1001,1,Athens,45,67,3,4250
1002,2,Sparta,46,67,5,3980

Conquers File Format

text

town_id,timestamp,new_player_id,old_player_id,new_alliance_id,old_alliance_id,town_points

Example:

text

1001,1645234567,5,1,103,101,4250

---

Building Tools with Grepolis Data

Creating a Simple Statistics Tool

PHP Example

php

<?php
class GrepolisDataParser {
    private $world;
    
    public function __construct($world) {
        $this->world = $world;
    }
    
    public function getPlayers() {
        $file = gzfile("http://{$this->world}.grepolis.com/data/players.txt.gz");
        $players = [];
        
        foreach ($file as $line) {
            $data = explode(',', trim($line));
            $players[] = [
                'id' => $data[0],
                'name' => urldecode($data[1]),
                'alliance' => $data[2],
                'points' => $data[3],
                'rank' => $data[4],
                'towns' => $data[5]
            ];
        }
        
        return $players;
    }
    
    public function getTopPlayers($limit = 10) {
        $players = $this->getPlayers();
        usort($players, function($a, $b) {
            return $a['points'] < $b['points'];
        });
        return array_slice($players, 0, $limit);
    }
}

// Usage
$parser = new GrepolisDataParser('en1');
$topPlayers = $parser->getTopPlayers(10);
print_r($topPlayers);
?>

JavaScript/Node.js Example

javascript

const zlib = require('zlib');
const https = require('https');

class GrepolisDataFetcher {
    constructor(world) {
        this.baseUrl = `http://${world}.grepolis.com/data/`;
    }

    async fetchData(fileName) {
        return new Promise((resolve, reject) => {
            https.get(this.baseUrl + fileName + '.txt.gz', (response) => {
                const chunks = [];
                response.on('data', (chunk) => chunks.push(chunk));
                response.on('end', () => {
                    const buffer = Buffer.concat(chunks);
                    zlib.gunzip(buffer, (err, decompressed) => {
                        if (err) reject(err);
                        resolve(decompressed.toString().split('\n'));
                    });
                });
            }).on('error', reject);
        });
    }

    async getPlayerRankings() {
        const data = await this.fetchData('players');
        return data
            .filter(line => line.trim())
            .map(line => {
                const [id, name, alliance, points, rank, towns] = line.split(',');
                return {
                    id,
                    name: decodeURIComponent(name),
                    alliance,
                    points: parseInt(points),
                    rank: parseInt(rank),
                    towns: parseInt(towns)
                };
            })
            .sort((a, b) => a.rank - b.rank);
    }
}

---

Grepolis APIs and Third-Party Tools

Community-Built APIs

Several developers have created RESTful APIs that wrap the raw Grepolis data:

1. Grepolis PHP API

php

// Example API endpoint structure
GET /api/players.php?world=en1
GET /api/alliances.php?world=en1&id=101
GET /api/towns.php?world=en1&ocean=45

2. JSON Response Format

json

{
  "success": true,
  "data": {
    "players": [
      {
        "id": "1",
        "name": "AlexTheGreat",
        "alliance_id": "101",
        "points": 25000,
        "rank": 1,
        "towns": 8,
        "ocean": 45
      }
    ],
    "timestamp": 1645234567,
    "world": "en1"
  }
}

Popular Third-Party Tools

Tool Name	Purpose	Features
Grepolis Map	Interactive world map	Town locations, alliance territories
Grepolis Stats	Player/Alliance statistics	Growth tracking, comparison tools
Conquer Monitor	Conquest tracking	Real-time alerts, patterns analysis
Alliance Analyzer	Alliance intelligence	Member activity, point distribution

---

Best Practices for Data Usage

1. Respect Server Resources

• Cache data locally for repeated access
• Implement rate limiting in your applications
• Use conditional requests when possible
• Minimum download frequency: Once per hour

2. Data Processing Guidelines

python

import time
import os
from datetime import datetime, timedelta

class CachedGrepolisData:
    def __init__(self, world, cache_duration=3600):
        self.world = world
        self.cache_duration = cache_duration
        self.cache_dir = 'cache'
        
        if not os.path.exists(self.cache_dir):
            os.makedirs(self.cache_dir)
    
    def get_data(self, data_type):
        cache_file = f"{self.cache_dir}/{self.world}_{data_type}.json"
        
        # Check cache
        if os.path.exists(cache_file):
            mod_time = datetime.fromtimestamp(os.path.getmtime(cache_file))
            if datetime.now() - mod_time < timedelta(seconds=self.cache_duration):
                with open(cache_file, 'r') as f:
                    return json.load(f)
        
        # Download fresh data
        data = self.download_data(data_type)
        
        # Save to cache
        with open(cache_file, 'w') as f:
            json.dump(data, f)
        
        return data

3. Data Validation

• Always validate downloaded file integrity
• Handle missing or malformed data gracefully
• Implement error logging for debugging

---

Common Use Cases

1. Alliance Recruitment

sql

-- Find potential recruits (high point players without alliances)
SELECT p.name, p.points, p.num_towns
FROM players p
WHERE p.alliance_id = 0
AND p.points > 5000
ORDER BY p.points DESC
LIMIT 20;

2. Enemy Activity Monitoring

python

def detect_suspicious_activity(player_id, days=7):
    # Analyze conquest patterns
    recent_conquers = get_player_conquers(player_id, days)
    town_growth = calculate_town_growth(player_id, days)
    
    if town_growth > 20:  # More than 20% growth
        return "RAPID_EXPANSION"
    elif len(recent_conquers) > 5:  # More than 5 conquests
        return "AGGRESSIVE"
    else:
        return "NORMAL"

3. Ocean Dominance Analysis

sql

-- Calculate alliance presence by ocean
SELECT 
    FLOOR(island_x/100) as ocean_x,
    FLOOR(island_y/100) as ocean_y,
    a.name as alliance_name,
    COUNT(t.town_id) as town_count
FROM towns t
JOIN islands i ON t.island_x = i.x AND t.island_y = i.y
JOIN players p ON t.player_id = p.player_id
JOIN alliances a ON p.alliance_id = a.alliance_id
GROUP BY ocean_x, ocean_y, a.alliance_id
ORDER BY ocean_x, ocean_y, town_count DESC;

---

Frequently Asked Questions (FAQs)

Q1: How often is Grepolis database updated?

The game data files are typically updated every hour. However, conquest data may have slight delays during peak times.

Q2: Can I access historical data?

The conquers.txt.gz file contains complete conquest history since world creation. Other files only show current state.

Q3: Is it legal to use Grepolis data?

Yes, InnoGames publicly provides this data for community tools and statistics. However, automated data collection should be done responsibly.

Q4: How do I handle special characters in town/player names?

Names are URL-encoded. Use urldecode() in PHP or decodeURIComponent() in JavaScript to properly display them.

Q5: What’s the best way to store Grepolis data?

Consider using:

• MySQL/PostgreSQL: For relational queries
• MongoDB: For flexible document storage
• Redis: For real-time caching
• CSV/JSON files: For simple applications

Q6: How can I track player growth over time?

python

def calculate_growth(player_id, start_date, end_date):
    start_data = get_player_snapshot(player_id, start_date)
    end_data = get_player_snapshot(player_id, end_date)
    
    growth = {
        'points': end_data['points'] - start_data['points'],
        'towns': end_data['towns'] - start_data['towns'],
        'rank_change': start_data['rank'] - end_data['rank']
    }
    
    growth['points_percentage'] = (growth['points'] / start_data['points']) * 100
    return growth

Q7: What are the rate limits for data access?

While no official limits are published, best practice suggests:

• Maximum 1 request per minute per IP
• Cache data for at least 1 hour
• Use multiple worlds sparingly

Q8: How do I identify inactive players?

sql

-- Players who haven't grown in 30 days
SELECT p.name, p.points, p.rank
FROM players p
LEFT JOIN conquers c ON p.player_id = c.new_player_id
WHERE c.timestamp < UNIX_TIMESTAMP(DATE_SUB(NOW(), INTERVAL 30 DAY))
GROUP BY p.player_id
HAVING MAX(c.timestamp) < UNIX_TIMESTAMP(DATE_SUB(NOW(), INTERVAL 30 DAY))
   OR COUNT(c.town_id) = 0;

Q9: Can I get data from closed worlds?

Generally, data for closed worlds is no longer available through the standard URLs. Some community archives may exist.

Q10: How accurate is the point calculation in towns.txt?

Town points are updated hourly and reflect the current town development level, including all buildings and research.

---

Conclusion

The Grepolis database system provides an incredible resource for players and developers to enhance their gaming experience. By understanding how to access and utilize this data effectively, you can:

• Gain competitive advantages through detailed analysis
• Build useful tools for your alliance and community
• Track progress and identify opportunities
• Create automated monitoring systems
• Develop statistical models for game strategy

Remember to always use this data responsibly, respect server resources, and contribute back to the community when possible. Whether you’re a casual player curious about statistics or a developer creating the next great Grepolis tool, the public game data is your gateway to deeper game understanding.