Cities Collective API Documentation

Overview

The Cities Collective API allows you to retrieve city data programmatically. All API endpoints require authentication using API keys.

🚀 New: HoF Creator API

Upload images to your cities programmatically using API keys. Perfect for creators who want to automate their image upload process.

View HoF Creator API Docs →

🔑 API Key Required

Contact an administrator to get an API key. API keys must be included in theX-API-Key header or as a Bearer token in the Authorization header.

Authentication

Include your API key in one of these ways:

X-API-Key Header

X-API-Key: cc_your_api_key_here

Authorization Header

Authorization: Bearer cc_your_api_key_here

Endpoints

Get Cities by Username

GET /api/v1/cities?username={username}

Retrieve all cities uploaded by a specific user.

Parameters:

username (required) - The username or email of the user

Response Fields:

user - User information (id, username, name)
cities - Array of city objects
total - Total number of cities
downloadUrl - Only included if city is downloadable
primaryImage - Only included if city has images

Example Response:

{
  "success": true,
  "data": {
    "user": {
      "id": 123,
      "username": "citybuilder"
    },
    "cities": [
      {
        "id": 456,
        "cityName": "New York",
        "mapName": "Manhattan",
        "population": 8500000,
        "money": 50000000,
        "xp": 150,
        "theme": "Modern",
        "gameMode": "Sandbox",
        "downloadable": true,
        "downloadUrl": "https://example.com/api/cities/456/download",
        "uploadedAt": "2024-01-15T10:30:00Z",
        "primaryImage": {
          "thumbnail": "https://...",
          "medium": "https://...",
          "large": "https://...",
          "original": "https://..."
        },
        "stats": {
          "likes": 25,
          "comments": 8
        }
      }
    ],
    "total": 1
  }
}

Get City by ID

GET /api/v1/cities/{cityId}

Retrieve detailed information about a specific city including all images, stats, and metadata.

Response Fields:

downloadUrl - Only included if city is downloadable
primaryImage - Only included if city has images
images - Array of all city images with metadata
stats - Like count, comment count, and total images
user - City owner information

Example Response:

{
  "success": true,
  "data": {
    "id": 456,
    "cityName": "New York",
    "mapName": "Manhattan",
    "population": 8500000,
    "money": 50000000,
    "xp": 150,
    "theme": "Modern",
    "gameMode": "Sandbox",
    "autoSave": true,
    "leftHandTraffic": false,
    "naturalDisasters": true,
    "unlockAll": false,
    "unlimitedMoney": false,
    "unlockMapTiles": true,
    "simulationDate": {"year": 2024, "month": 6, "day": 15},
    "contentPrerequisites": ["DLC1", "DLC2"],
    "modsEnabled": ["mod1", "mod2"],
    "fileName": "newyork.cok",
    "downloadable": true,
    "downloadUrl": "https://example.com/api/cities/456/download",
    "uploadedAt": "2024-01-15T10:30:00Z",
    "updatedAt": "2024-01-15T10:30:00Z",
    "primaryImage": {
      "id": 789,
      "thumbnail": "https://...",
      "medium": "https://...",
      "large": "https://...",
      "original": "https://..."
    },
    "images": [
      {
        "id": 789,
        "fileName": "image1.webp",
        "originalName": "screenshot.jpg",
        "fileSize": 2048576,
        "mimeType": "image/webp",
        "width": 1920,
        "height": 1080,
        "isPrimary": true,
        "sortOrder": 0,
        "uploadedAt": "2024-01-15T10:30:00Z",
        "urls": {
          "thumbnail": "https://...",
          "medium": "https://...",
          "large": "https://...",
          "original": "https://..."
        }
      }
    ],
    "stats": {
      "likes": 25,
      "comments": 8,
      "totalImages": 3
    },
    "user": {
      "id": 123,
      "username": "citybuilder"
    }
  }
}

CORS Support

The API supports Cross-Origin Resource Sharing (CORS) for browser-based applications. All endpoints support OPTIONS preflight requests with the following headers:

Access-Control-Allow-Origin: *

Access-Control-Allow-Methods: GET, POST, PUT, DELETE, OPTIONS

Access-Control-Allow-Headers: Content-Type, Authorization, X-API-Key

Error Responses

All error responses follow this format:

{
  "error": "Error message description"
}

401 Unauthorized: Invalid or missing API key

400 Bad Request: Missing required parameters (e.g., username)

404 Not Found: User or city not found

500 Internal Server Error: Server error

Rate Limiting

API requests are currently not rate limited, but please use the API responsibly. If you need higher limits for production use, please contact an administrator.