tibiadata-api-go

README

TibiaData API in Golang

TibiaData API written in Golang and deployed in container (version v3 and above).

Documentation of API endpoints can be found on docs.tibiadata.com.

Table of Contents

• API versions
• How to use
  • Helm
  • Docker
  • Docker-compose
  • Local development
  • Environment variables
  • Deployment note
• API documentation
  • Available endpoints
  • Deprecated endpoints
  • Restricted endpoints
• CI authentication
• General information
• Credits

API versions

Here is a summary of the TibiaData API versions

v5 endpoints are available alongside v4 in preparation for the next release
v4 is released (since 1st December 2024 )
v3 is deprecated (since 31rd January 2024)
v2 is deprecated (since 30rd April 2022)
v1 is deprecated (since 30rd April 2018)

How to use

You can either use it in a Docker container or go download the code and deploy it yourself on any server.

Keep in mind that there are restrictions on tibia.com that might impact the usage of the application being hosted yourself.

Helm

We have a Helm chart available for you to use to deploy your application to Kubernetes.

All our charts are available through charts.tibiadata.com.

Add the repository

helm repo add tibiadata https://charts.tibiadata.com
helm repo update

Search for the chart

helm repo search tibiadata

The charts-repository is located in tibiadata-helm-charts.

Docker

Our images are available on both GitHub Container Registry and Docker Hub.

This is how to pull and run the latest release of TibiaData from GHCR:

docker pull ghcr.io/tibiadata/tibiadata-api-go:latest
docker run -p 127.0.0.1:80:8080/tcp --rm -it ghcr.io/tibiadata/tibiadata-api-go:latest

You can also use Docker Hub to pull your images from.

If you want to run the latest code you can switch from latest to edge.

Docker-compose

This is a simple example on how you can get up and running with TibiaData in docker-compose, which will be running on port 8080 and be exposed locally.

version: "3"

services:
  tibiadata:
    image: ghcr.io/tibiadata/tibiadata-api-go:latest
    restart: always
    environment:
      - TIBIADATA_HOST=tibiadata.example.com
    ports:
      - 8080:8080

Local development

Build the code on your computer

docker build -t tibiadata .

Run your build locally

docker run -p 127.0.0.1:80:8080/tcp --rm -it tibiadata

Environment variables

The following environment variables can be used to configure the API.

Variable	Default	Description
DEBUG_MODE	false	Enables verbose upstream HTTP debug/trace (resty) and lowers the default log level when TIBIADATA_LOG_LEVEL is unset.
GIN_MODE	release	Gin mode: release, debug or test.
GIN_TRUSTED_PROXIES	(none)	Comma-separated list of trusted proxies (IPs/CIDRs). When unset, no proxies are trusted.
TIBIADATA_CACHE_CONTROL_HEADERS	true	Adds fixed, endpoint-specific Cache-Control headers to successful data responses (see below).
TIBIADATA_EDITION	open-source	Edition name reported by the API.
TIBIADATA_HOST	(empty)	Hostname used when generating API URLs (e.g. in news and the OpenAPI docs).
TIBIADATA_LOG_CF_RAY	false	Logs Cloudflare's Cf-Ray header as request_id when true. Enable only when the API is reachable exclusively through Cloudflare.
TIBIADATA_LOG_FORMAT	text	Log output format: text or json.
TIBIADATA_LOG_LEVEL	info (or debug when DEBUG_MODE=true and unset)	Application log level: debug, info, warn, error.
TIBIADATA_OTEL_ENABLED	false	Enables OpenTelemetry traces and metrics (see OpenTelemetry).
TIBIADATA_PROTOCOL	https	Protocol used together with TIBIADATA_HOST when generating API URLs.
TIBIADATA_PROXY	www.tibia.com	Domain to fetch data from instead of www.tibia.com, e.g. a caching proxy.
TIBIADATA_PROXY_PROTOCOL	https	Protocol for TIBIADATA_PROXY (http or https). Only used when TIBIADATA_PROXY is set.
TIBIADATA_RESTRICTION_MODE	false	Enables restriction mode, which disables expensive requests (e.g. highscores with vocation all).
TIBIA_FANSITEAPI_TOKEN	(empty)	Token for the official Tibia Fansite API. Enables the Fansite API when valid.

Request correlation

Set TIBIADATA_LOG_CF_RAY=true to log Cloudflare's Cf-Ray header as request_id when present. Restrict origin access to Cloudflare so that clients cannot send arbitrary Cf-Ray values directly to the API.

OpenTelemetry

Set TIBIADATA_OTEL_ENABLED=true to enable OpenTelemetry traces and metrics. When enabled, the API:

• creates a server span for each incoming request and continues traces from incoming W3C traceparent headers,
• creates client spans for upstream requests (e.g. to tibia.com) and propagates the trace context to them,
• records HTTP server and client metrics such as http.server.request.duration (request count, latency, method, route and status code),
• adds trace_id and span_id to request logs, so logs can be correlated with traces.

Probe endpoints (/ping, /health, /healthz, /readyz) are included in metrics but not traced.

All other settings use the standard OpenTelemetry environment variables, for example:

Variable	Default	Description
OTEL_SERVICE_NAME	tibiadata-api-go	Service name reported in telemetry.
OTEL_RESOURCE_ATTRIBUTES	(empty)	Additional resource attributes, e.g. deployment.environment=production.
OTEL_TRACES_EXPORTER	otlp	Trace exporter: otlp, console or none.
OTEL_METRICS_EXPORTER	otlp	Metrics exporter: otlp, prometheus, console or none.
OTEL_EXPORTER_OTLP_ENDPOINT	http://localhost:4318	OTLP collector endpoint.
OTEL_EXPORTER_OTLP_PROTOCOL	http/protobuf	OTLP protocol: http/protobuf or grpc.
OTEL_TRACES_SAMPLER	parentbased_always_on	Trace sampler, e.g. parentbased_traceidratio together with OTEL_TRACES_SAMPLER_ARG=0.1.
OTEL_EXPORTER_PROMETHEUS_HOST / OTEL_EXPORTER_PROMETHEUS_PORT	localhost / 9464	Listen address of the Prometheus /metrics endpoint when OTEL_METRICS_EXPORTER=prometheus. Set the host to 0.0.0.0 to expose it outside the container.

A signal whose exporter is set to none creates no spans or measurements. When telemetry is disabled, or both exporters are none, no instrumentation is installed at all. For example, to collect only metrics:

TIBIADATA_OTEL_ENABLED=true
OTEL_TRACES_EXPORTER=none
OTEL_METRICS_EXPORTER=prometheus
OTEL_EXPORTER_PROMETHEUS_HOST=0.0.0.0

Deployment note

You should consider to add a layer in front of this application, so you can do caching of endpoints, access controll or what ever your needs are.

We do so at least by using Kong API Gateway, which solves features like caching, rate-limiting, authentication and more.

Successful data responses include a Cache-Control header with fixed, endpoint-specific cache lifetimes: characters and houses 300 seconds, guilds 120 seconds, highscores and news 900 seconds, and worlds 60 seconds. Both max-age and s-maxage use the configured lifetime; upstream Age, Date, and Last-Modified headers do not affect it. Set TIBIADATA_CACHE_CONTROL_HEADERS=false to disable them.

API documentation

The hosted API documentation for our api.tibiadata.com service can be viewd at docs.tibiadata.com.

There is a swagger-generated documentation available for download on the GitHub Release of the version you are looking for.

The official Tibia Fansite API OpenAPI specification is also available. Access to this API is limited to participants in Tibia's official Fansite Program.

Available endpoints

Those are the current existing endpoints.

• GET /
• GET /ping
• GET /healthz
• GET /readyz
• GET /v4/boostablebosses
• GET /v4/character/:name
• GET /v4/creature/:race
• GET /v4/creatures
• GET /v4/fansites
• GET /v4/guild/:name
• GET /v4/guilds/:world
• GET /v4/highscores/:world/:category/:vocation/:page
• GET /v4/house/:world/:house_id
• GET /v4/houses/:world/:town
• GET /v4/killstatistics/:world
• GET /v4/news/archive
• GET /v4/news/archive/:days
• GET /v4/news/id/:news_id
• GET /v4/news/latest
• GET /v4/news/newsticker
• GET /v4/spell/:spell_id
• GET /v4/spells
• GET /v4/world/:name
• GET /v4/worlds
• GET /v5/boostablebosses
• GET /v5/character/:name
• GET /v5/creature/:race
• GET /v5/creatures
• GET /v5/fansites
• GET /v5/guild/:name
• GET /v5/guilds/:world
• GET /v5/highscores/:world/:category/:vocation/:page
• GET /v5/house/:world/:house_id
• GET /v5/houses/:world/:town
• GET /v5/killstatistics/:world
• GET /v5/news/archive
• GET /v5/news/archive/:days
• GET /v5/news/id/:news_id
• GET /v5/news/latest
• GET /v5/news/newsticker
• GET /v5/spell/:spell_id
• GET /v5/spells
• GET /v5/world/:name
• GET /v5/worlds
• GET /versions

Highscore categories

On /v5/highscores, category aliases and case variants (for example magic, mlvl or MagicLevel) are answered with a 301 redirect to the canonical lowercase category name (for example magiclevel), so each category is served from a single cacheable URL. /v4/highscores keeps serving aliases directly. Unknown categories return HTTP 404 with JSON error 11004.

Deprecated Endpoints

In addition to the deprecated API versions like v1, v2 and v3, there are also some endpoints that are deprecated. As of now, those are:

• GET /health

Restricted endpoints

There are some endpoints that can be deviant between the container documentation and the hosted version. This is due to restricted mode that restrict certain API actions due to high load on the tibia.com servers.

• /v4/highscores and /v5/highscores-filtering on vocation is removed, only the all category is valid.

Fansite API

The Fansite API allows you to access data provided by the official Tibia Fansite API using json and not by parsing HTML pages. To be able to use this you need to set a valid TIBIA_FANSITEAPI_TOKEN as an environment variable, which will be provided by CipSoft as part of their official Fansite program.

On startup, when a valid token is configured, the API performs a best-effort check against the Fansite API status endpoint and logs whether it currently reports as available. This check is purely informational and never prevents the application from starting, since it falls back to HTML scraping regardless.

The data returned by the HTML and JSON collector can differ, which may lead to discrepancies in the information provided by the two sources. Such findings are:

• Account achievements on the HTML page do not reflect the actual achievements grade as correctly shown by the JSON collector.

CI authentication

The build and documentation workflows use the tibiadata-ci GitHub App to send cross-repository repository_dispatch events. Organization Actions variable TIBIADATA_CI_CLIENT_ID and secret TIBIADATA_CI_PRIVATE_KEY must be available to this repository. The app must be installed on tibiadata-api-docs, tibiadata-argocd-app-of-apps, and tibiadata-helm-charts with Contents: write permission.

Each dispatch creates a short-lived installation token restricted to its destination repository and Contents: write. The token is revoked at the end of the job. Other operations continue to use the workflow's GITHUB_TOKEN.

General information

Tibia is a registered trademark of CipSoft GmbH. Tibia and all products related to Tibia are copyright by CipSoft GmbH.

Credits

• Authors: Tobias Lindberg – List of contributors
• Distributed under MIT License