{% extends "base.html" %} {% block title %}API Documentation - {{ app_name }}{% endblock %} {% block content %}

API Documentation

RESTful API for programmatic access to geo-blocking configuration generation.

Base URL:
GET /api/countries Get available countries
Description

Returns a list of all available countries with their ISO codes and flag emojis.

Response Schema
{
  "success": true,
  "countries": [
    {
      "code": "CN",
      "name": "China",
      "flag": "🇨🇳"
    }
  ]
}
Try it out
GET /api/database/status Check database status
Description

Returns the current status of the MaxMind GeoIP database, including last update time and whether an update is needed.

Response Schema
{
  "success": true,
  "exists": true,
  "needs_update": false,
  "last_update": "2026-02-10T08:00:00",
  "file_size": 5242880,
  "auto_update": true
}
Try it out
GET /api/cache/redis/status Redis L1 cache
Description

Redis (L1: configs/networks)

Response Schema
{
  "success": true,
  "enabled": true,
  "health": {
    "connected": true,
    "memory_peak_mb": 474.25,
    "memory_used_mb": 241.38,
    "status": "healthy"
  },
  "stats": {
    "country_keys": 119,
    "config_keys": 0,
    "total_keys": 119,
    "total_size_mb": 240.4
  }
}
Fields
Name Type Description
enabled boolean Redis configured (REDISENABLED=false)
health.connected boolean TCP connection OK
health.memory_peak_mb float Redis peak memory usage
stats.country_keys integer geobancountry* keys (119 networks cached)
stats.config_keys integer geoipconfig* + geobanconfig* (0 configs)
Cache Flow
L1 Redis: configs/networks (<1s) → L2 SQLite: fallback networks → L3 MaxMind: live scan
Error Handling
Redis offline? → Returns partial stats + "error": "Connection refused"
Logs: ConnectionError: Error 111 connecting to localhost:6379
Try it out
GET /api/cache/sqlite/status SQLite L2 cache
Description

SQLite L2 cache (`networks_cache.db`): country networks from MaxMind scans.

Response Schema
{
  "success": true,
  "exists": true,
  "file_size_mb": 1439.54,
  "total_countries": 123,
  "total_networks": 13728494,
  "top_countries": [
    {"code": "US", "networks": 5801506}
  ]
}
Fields
NameTypeDescription
existsbooleanDB file exists
file_size_mbfloatDB size on disk
total_countriesintegerCountries with cached networks
top_countriesarrayTop 5 by network count
Try it out
POST /api/cache/invalidate/<country_code> Invalidate country cache
Description

Clears Redis L1 cache for specific country: networks + all configs containing it. Forces fresh SQLite/MaxMind scan next time.

Path Parameter
NameTypeDescription
country_codestringISO 3166-1 alpha-2 (e.g. CN, RU)
Response Schema
{
  "success": true,
  "deleted": 5,
  "country": "CN",
  "details": {
    "country_cache": 1,
    "config_caches": 4
  }
}
What it deletes
  • geoban:country:CN - country networks
  • geoban:config:*[CN] - configs with CN
Try it out

Enter country code (e.g. CN):

cURL Example
curl -X POST /api/cache/invalidate/CN
POST /api/database/update Update database manually
Description

Manually triggers a download and update of the MaxMind GeoIP database from configured sources.

Response Schema
{
  "success": true,
  "url": "https://github.com/...",
  "size": 5242880
}
Try it out
GET /api/progress Get current generation progress
Description

Returns the current progress status of any active configuration generation process. Poll this endpoint to monitor long-running operations.

Response Schema
{
  "active": true,
  "message": "[1/3] CN: Scanning MaxMind: 234 networks found",
  "progress": 30,
  "total": 100
}
Fields
Name Type Description
active boolean Whether a generation process is currently active
message string Current progress message with detailed status
progress integer Current progress value (0-100)
total integer Total progress value (always 100)
Try it out
Polling Example
// Poll every 500ms during generation
const pollProgress = setInterval(async () => {
  const response = await fetch('/api/progress');
  const data = await response.json();
  
  if (data.active) {
    console.log(`Progress: ${data.progress}% - ${data.message}`);
  } else {
    clearInterval(pollProgress);
    console.log('Generation complete!');
  }
}, 500);
POST /api/generate/preview Preview configuration (JSON response)
Description

Generates configuration and returns it as JSON (instead of file download). Perfect for previewing or integrating into other applications.

Request Body
{
  "countries": ["CN", "RU"],
  "app_type": "nginx",
  "app_variant": "map",
  "aggregate": true,
  "use_cache": true
}
Parameters
Name Type Required Description
countries array required List of ISO 3166-1 alpha-2 country codes
app_type string required One of: nginx, apache, haproxy, raw-cidr
app_variant string required Configuration style (depends on app_type)
aggregate boolean optional Aggregate IP networks to reduce count (default: true)
use_cache boolean optional Use Redis cache if available (default: true). Set to false to force fresh data from SQLite/MaxMind
Response Schema
{
  "success": true,
  "config": "# Nginx Map Module Configuration\n...",
  "stats": {
    "countries": 2,
    "total_networks": 4567,
    "per_country": {
      "CN": 2834,
      "RU": 1733
    }
  },
  "from_cache": true,
  "cache_type": "redis",
  "generated_at": "2026-02-16T10:30:00"
}
Response Fields
Name Type Description
from_cache boolean Whether the config was served from cache or freshly generated
cache_type string redis (from Redis cache) or sqlite (from SQLite/fresh scan)
generated_at string ISO 8601 timestamp when the config was generated
cURL Examples

With cache (default):

curl -X POST /api/generate/preview \
  -H "Content-Type: application/json" \
  -d '{
    "countries": ["CN", "RU"],
    "app_type": "nginx",
    "app_variant": "map",
    "aggregate": true,
    "use_cache": true
  }' | jq .

Force fresh data (bypass cache):

curl -X POST /api/generate/preview \
  -H "Content-Type: application/json" \
  -d '{
    "countries": ["CN", "RU"],
    "app_type": "nginx",
    "app_variant": "map",
    "aggregate": true,
    "use_cache": false
  }' | jq .
POST /api/generate/raw Generate raw blocklist (TXT/CSV/JSON/JS)
Description

Generates a raw blocklist without application-specific configuration. Use this endpoint for programmatic integrations when you need structured output (JSON) or a JS-wrapped JSON payload.

Request Body
{
  "countries": ["CN", "RU"],
  "app_type": "raw-json",
  "aggregate": true,
  "use_cache": true,
  "as_js": false,
  "js_var": "geoipBlocklist"
}
Parameters
Name Type Required Description
countries array required List of ISO 3166-1 alpha-2 country codes
app_type string optional Output format selector. Examples: raw-json (JSON), raw-json + as_js=true (JS wrapper).
aggregate boolean optional Aggregate IP networks (default: true)
use_cache boolean optional Use Redis cache if available (default: true)
Only for raw-json. When true, wraps JSON into JavaScript and returns application/javascript as: const <js_var> = {...};
js_var string optional Variable name used by as_js wrapper (default: geoipBlocklist).
Responses
Mode Content-Type Body
raw-cidr_txt text/plain One CIDR per line
raw-cidr_csv text/csv CSV export
raw-cidr_json application/json JSON object with countries, networks, count, aggregated
raw-cidr_json + as_js=true application/javascript const <js_var> = {...};
Responses
Mode Content-Type Body
raw-cidr_txt text/plain One CIDR per line
raw-cidr_csv text/csv CSV export
raw-json application/json JSON object with generated_at, countries, networks, total_networks
raw-json + as_js=true application/javascript const <js_var> = {...};
Response Headers
Header Description
X-From-Cache true or false - indicates if served from Redis
X-Cache-Type redis-full or computed cache type (e.g. hybrid)
X-Generated-At Timestamp when config was generated
cURL Examples

TXT (default):

curl -X POST /api/generate/raw \
  -H "Content-Type: application/json" \
  -d '{
    "countries": ["CN", "RU"],
    "app_type": "raw-cidr_txt",
    "aggregate": true,
    "use_cache": true
  }' \
  -o blocklist.txt

CSV:

curl -X POST /api/generate/raw \
  -H "Content-Type: application/json" \
  -d '{
    "countries": ["CN", "RU"],
    "app_type": "raw-cidr_csv",
    "aggregate": true,
    "use_cache": true
  }' \
  -o blocklist.csv

JSON:

curl -X POST /api/generate/raw \
  -H "Content-Type: application/json" \
  -d '{
    "countries": ["CN", "RU"],
    "app_type": "raw-json",
    "aggregate": true,
    "use_cache": true
  }' \
  -o blocklist.json

JS-wrapped JSON:

curl -X POST /api/generate/raw \
  -H "Content-Type: application/json" \
  -d '{
    "countries": ["CN", "RU"],
    "app_type": "raw-json",
    "aggregate": true,
    "use_cache": true,
    "as_js": true,
    "js_var": "geoipBlocklist"
  }' \
  -o blocklist.js
POST /api/generate Generate application configuration
Description

Generates application-specific geo-blocking configuration for Nginx, Apache, or HAProxy and returns it as a downloadable file.

Request Body
{
  "countries": ["CN", "RU"],
  "app_type": "nginx",
  "app_variant": "map",
  "aggregate": true,
  "use_cache": true
}
Parameters
Name Type Required Description
countries array required List of ISO 3166-1 alpha-2 country codes
app_type string required One of: nginx, apache, haproxy
app_variant string required Configuration style (depends on app_type)
aggregate boolean optional Aggregate IP networks (default: true)
use_cache boolean optional Use Redis cache if available (default: true)
Available Variants
  • nginx: geo, map, deny
  • apache: 22 (Apache 2.2), 24 (Apache 2.4)
  • haproxy: acl, lua, map
Response

Returns configuration file as text/plain with Content-Disposition header for download.

Response Headers
Header Description
X-From-Cache true or false
X-Cache-Type redis or sqlite
X-Generated-At ISO 8601 timestamp
Cache Behavior
With Redis enabled:
  • use_cache: true - Check Redis first, return cached config if available (fast, <1s)
  • use_cache: false - Bypass Redis, fetch from SQLite cache or scan MaxMind (slower, 5-30s)
cURL Examples

With cache (recommended for production):

curl -X POST /api/generate \
  -H "Content-Type: application/json" \
  -d '{
    "countries": ["CN", "RU"],
    "app_type": "nginx",
    "app_variant": "map",
    "aggregate": true,
    "use_cache": true
  }' \
  -o geoblock.conf

# Check if it was cached:
curl -I -X POST /api/generate \
  -H "Content-Type: application/json" \
  -d '{"countries":["CN"],"app_type":"nginx","app_variant":"map"}' \
  | grep "X-From-Cache"

Force fresh scan (for testing or updates):

curl -X POST /api/generate \
  -H "Content-Type: application/json" \
  -d '{
    "countries": ["CN", "RU"],
    "app_type": "nginx",
    "app_variant": "map",
    "aggregate": true,
    "use_cache": false
  }' \
  -o geoblock_fresh.conf
{% endblock %} {% block scripts %} {% endblock %}