Regions & categories — API reference

Two read-only endpoints that return the full catalog used by filters.regions[] and filters.categories[] on forecasts and drivers. They are discovery only — the only enforced rule is integer range 1–9999.

Both endpoints require Authorization: Bearer with an API key and share the same response shape and error codes.

Call the endpoint

GET /api/v1/regions

Returns all regions, sorted by integer id ascending.

curl

curl -sS -H "Authorization: Bearer $SYBILION_API_TOKEN" \
  https://api.sybilion.dev/api/v1/regions \
  | jq '.items | length'

Python

import os

from sybilion import Client

client = Client(token=os.environ["SYBILION_API_TOKEN"])

regions = client.list_regions()
print(len(regions.items), "regions; first:", regions.items[0])

Go

package main

import (
	"context"
	"fmt"
	"log"
	"os"

	"go.sybilion.dev/sybilion"
)

func main() {
	c := sybilion.New(sybilion.Options{
		Token: os.Getenv("SYBILION_API_TOKEN"),
	})

	resp, err := c.ListRegions(context.Background())
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(len(resp.Items), "regions")
}

R

library(sybilion)

cl <- sybilion_client(token = Sys.getenv("SYBILION_API_TOKEN"))
regions <- cl$raw$ApiV1RegionsGet()$content$items
cat(length(regions), "regions; first:", regions[[1]]$name, "\n")

Java

import com.sybilion.Client;
import com.sybilion.Options;

Client c = new Client(Options.builder().token(System.getenv("SYBILION_API_TOKEN")).build());
var regions = c.defaultApi().apiV1RegionsGet();
System.out.println(regions.getItems().size() + " regions");

GET /api/v1/categories

Returns all categories, sorted by integer id ascending.

curl

curl -sS -H "Authorization: Bearer $SYBILION_API_TOKEN" \
  https://api.sybilion.dev/api/v1/categories \
  | jq '.items[0]'

Python

categories = client.list_categories()
print(len(categories.items), "categories; first:", categories.items[0])

Go

resp, err := c.ListCategories(context.Background())
if err != nil {
	log.Fatal(err)
}
fmt.Println(len(resp.Items), "categories")

R

categories <- cl$raw$ApiV1CategoriesGet()$content$items
cat(length(categories), "categories; first:", categories[[1]]$name, "\n")

Java

var categories = c.defaultApi().apiV1CategoriesGet();
System.out.println(categories.getItems().size() + " categories");

Response

Regions

{
  "items": [
    {
      "id": 42,
      "name": "Europe",
      "latitude": 48.0,
      "longitude": 10.0
    }
  ]
}

Categories

{
  "items": [
    {
      "id": 3,
      "name": "Energy"
    }
  ]
}

items is the complete listing — no pagination.

Field reference

Regions

Field	Meaning
id	Integer identifier. Use this value in filters.regions[].
name	Human-readable label.
latitude, longitude	Geographic coordinates (0.0 when not applicable).

Categories

Field	Meaning
id	Integer identifier. Use this value in filters.categories[].
name	Human-readable label.

Common errors

Code	Cause	What to do
401	Missing or invalid bearer token.	Check the API key.
502	Dimensions backend unreachable.	Retry; contact [email protected] if it persists.
503	Dimensions backend not enabled for this account.	Contact [email protected].