Skip to content
mavrovde edited this page Nov 1, 2026 · 3 revisions

FAQ

Is the API available? Not yet. The project is in its design phase; see Project Status. ViaFrei's data is available today through its MCP server for AI assistants and on viafrei.de.

How is the API different from the MCP server? Both read the same data through the same published read contract. The MCP server is designed for AI assistants: tools, natural-language descriptions, conversational answers. The API is designed for software: stable REST paths, JSON and GeoJSON, OpenAPI 3.1, cursors, caching headers, keys and priority tiers. For the same input, an API endpoint answers the same facts as the matching MCP capability, and this is tested.

Will it be free? Plans and their limits are not decided yet. See the open decisions on Project Status.

How do I get a key? At first, keys will be issued by the operator. Self-service sign-up is not planned for the first release. The process will be announced in the documentation when the API launches.

Why do I have to show attribution? Because the data's licences require it. Every response carries the attribution and any condition notes in meta. If you display the data, display those too. See Principles.

Why was my request refused with source-not-permitted? Your key's plan or use class does not cover that source's licence, or the source requires terms you have not accepted. Composed answers report such parts as not_permitted instead of failing completely.

Why can I not filter by any field I like? Open-ended filters on a shared database are a reliability risk and say nothing about the domain. The API offers features ("conditions along this motorway") rather than tables. If you need a question answered that the API cannot answer, open an issue describing it. See Domain Model.

Why does a history request need from and to? A bounded window keeps every history query on a small, indexed slice of time-series data, which is how the API keeps its 2 second promise.

What happens when the API is busy? Higher tiers are served first. If your request cannot be served in time, you get 429 with Retry-After at once, rather than a slow failure. See Rate Limits and Priority.

Can I cache responses? Yes, and you should. Responses carry ETag and Cache-Control; send If-None-Match and you will get a cheap 304 when nothing changed. A 304 still counts toward your quota, but it is fast.

What time zone are times in? All instants are ISO 8601 in UTC (Z). Where people read them, a …Local companion field carries the Europe/Berlin rendering with its offset (Spec: Scope, Conventions and References).

Will v1 change under me? Within v1 only additive changes are made; ignore fields you do not know. Breaking changes go to a new version with at least six months' notice through Deprecation and Sunset headers. See API Design.

Why not simply TypeScript, like the rest of ViaFrei? TypeScript is still a candidate, with a full design of its own (Architecture: TypeScript). Go and Rust are the owner's preferred candidates because they offer a smaller memory footprint and, in Go's case, native server-side query cancellation, and because the reuse advantage of TypeScript matters less in a self-contained repository. The three are compared criterion by criterion on Stack Comparison.

Why no API gateway or Redis? At the first stage, everything they would do is done exactly and more cheaply inside one process, and a gateway cannot see the database pool that priority admission must protect. Both remain options for a multi-instance stage. See Technology: Gateways and Key Management.

Does the API reveal where or how ViaFrei gets its data? No. The API is about access to data. Each response names the data's publisher and licence because attribution requires it, and nothing more.

How do I report a security problem? Use private vulnerability reporting on the repository's Security tab. Please do not open a public issue. See Contributing.

Home

About

Design

Data Model

Technical specification

Testing

Engineering

Technology choice

Reference

Clone this wiki locally