Getting started overview
To integrate Tankerkoenig's real-time fuel price data into an application, developers follow a standard sequence: account creation, API key retrieval, and sending a request. The API provides endpoints for retrieving fuel station lists, current prices, and individual station details across Germany, leveraging data from the Market Transparency Unit for Fuels (MTS-K) (Tankerkoenig API documentation). The free tier allows for up to 50 requests per day, suitable for initial development and testing.
This guide outlines the essential steps to make a first successful call to the Tankerkoenig API:
- Register for a Tankerkoenig account.
- Locate and copy your unique API key.
- Construct and execute a basic API request to retrieve fuel station data.
The API utilizes a RESTful architecture, accepting HTTP GET requests and returning data in JSON format (JSON standard specification). Authentication is handled by including your API key as a query parameter in each request.
Quick reference table
| Step | What to do | Where |
|---|---|---|
| 1. Sign up | Create a user account | Tankerkoenig registration page |
| 2. Get API Key | Retrieve your personal API key | Tankerkoenig API key management |
| 3. Make Request | Send a GET request with your API key | Any HTTP client (e.g., cURL, browser, programmatic library) |
| 4. Parse Response | Extract data from the JSON response | Your application's code |
Create an account and get keys
Access to the Tankerkoenig API requires an API key, which is obtained by registering a user account. The registration process is straightforward and provides immediate access to your unique key.
Step 1: Register for a Tankerkoenig account
Navigate to the Tankerkoenig API registration page. You will be prompted to provide an email address and create a password. After submitting the form, a confirmation email will be sent to the address provided. Follow the instructions in the email to activate your account. This typically involves clicking a verification link.
Step 2: Obtain your API key
Once your account is activated, log in to the Tankerkoenig API portal. Your personal API key will be displayed on your profile page or specifically on the API Key management section. The key is a unique alphanumeric string that authenticates your requests to the API. It is crucial to keep this key confidential to prevent unauthorized usage of your allocated request quota.
The API key is passed as a query parameter named apikey in all API calls. For example, a request might look like https://creativecommons.tankerkoenig.de/api/v4/stations/prices?apikey=YOUR_API_KEY&ids=STATION_ID.
Your first request
With an active account and API key, you can now make your first API call. A common starting point is to retrieve a list of fuel stations near a specific geographic coordinate or to get the prices for specific stations.
Example: Get fuel stations within a radius
This example demonstrates how to find fuel stations within a 5 km radius of a specified latitude and longitude (e.g., 52.5200° N, 13.4050° E, which is Berlin, Germany). The API endpoint for this is /list.
Request parameters:
lat: Latitude (e.g.,52.5200)lng: Longitude (e.g.,13.4050)rad: Radius in kilometers (e.g.,5)sort: Sorting order (e.g.,distfor distance)type: Fuel type (e.g.,e5for Super E5)apikey: Your unique Tankerkoenig API key
Constructing the URL:
https://creativecommons.tankerkoenig.de/api/v4/stations/list?lat=52.5200&lng=13.4050&rad=5&sort=dist&type=e5&apikey=YOUR_API_KEY
Replace YOUR_API_KEY with the actual key obtained from your Tankerkoenig account.
Making the request using cURL:
cURL is a widely available command-line tool for making HTTP requests (cURL documentation). Open your terminal or command prompt and execute the following command:
curl "https://creativecommons.tankerkoenig.de/api/v4/stations/list?lat=52.5200&lng=13.4050&rad=5&sort=dist&type=e5&apikey=YOUR_API_KEY"
Remember to substitute YOUR_API_KEY with your valid key.
Expected JSON response structure (abbreviated):
{
"ok": true,
"stations": [
{
"id": "44f777e3-1111-4444-8888-999999999999",
"name": "Aral Tankstelle",
"brand": "ARAL",
"street": "Hauptstr.",
"houseNumber": "1",
"postCode": 10115,
"city": "Berlin",
"lat": 52.5210,
"lng": 13.4060,
"dist": 0.1,
"e5": 1.759,
"e10": 1.729,
"diesel": 1.699,
"isOpen": true,
"station_id": "44f777e3-1111-4444-8888-999999999999"
}
// ... more stations
]
}
A successful response will have "ok": true and an array of stations, each containing details like name, address, coordinates, current fuel prices (e.g., e5, e10, diesel), and an isOpen status. The prices are provided in Euros per liter.
Common next steps
After successfully making your first request and understanding the basic response structure, several common next steps can enhance your integration with the Tankerkoenig API:
1. Implement error handling
The API response includes an ok field to indicate success or failure. In case of an error ("ok": false), the response will typically contain an message field providing details about the issue. Implement logic in your application to check this field and handle different error codes or messages gracefully (Tankerkoenig API error codes).
2. Explore other endpoints
The Tankerkoenig API offers several endpoints beyond listing stations:
/prices: Get current prices for a specific list of station IDs. This is efficient for regularly updating prices for known stations./detail: Retrieve detailed information for a single station ID, including opening hours and address specifics.
Refer to the Tankerkoenig API reference for a complete list of available endpoints and their parameters.
3. Manage API key security
Your API key grants access to your account's quota. Best practices for API key security include:
- Do not embed keys directly in client-side code: If your application runs in a browser, proxy requests through your own backend server to keep the API key server-side.
- Use environment variables: Store your API key as an environment variable in your server-side applications or development environment, rather than hardcoding it.
- Restrict access: Limit who has access to your API key within your development team.
4. Implement caching strategies
To optimize usage and stay within the request limits (50 requests/day for the free tier, more for paid plans), consider caching fuel price data. Fuel prices do not change every second, so fetching data at reasonable intervals (e.g., every 5-10 minutes) and serving cached data for intermediate requests can be effective.
5. Upgrade your plan
If your application requires more than 50 requests per day, you will need to upgrade to a paid plan. Tankerkoenig offers various tiers, starting at 2.50 EUR per month for 5,000 requests per day (Tankerkoenig pricing details). Review the data license and pricing page to choose a plan that fits your application's needs.
Troubleshooting the first call
Encountering issues during the initial API call is common. Here are some troubleshooting tips for the Tankerkoenig API:
1. Invalid or missing API key
Symptom: The API returns an error message indicating an invalid API key, or a general authentication failure.
Solution: Double-check that your API key is correctly copied and pasted into the apikey query parameter. Ensure there are no extra spaces or characters. Verify that your account is active and the key has not been revoked. Log in to your Tankerkoenig API key management page to confirm your key's validity.
2. Incorrect URL or endpoint
Symptom: The API returns a 404 Not Found error, or a response indicating an unknown endpoint.
Solution: Carefully review the API endpoint URL. Ensure it matches the documentation exactly, including the /v4/ segment and the correct endpoint name (e.g., /stations/list, /prices, /detail). The base URL is https://creativecommons.tankerkoenig.de/api/v4/ (Tankerkoenig API reference).
3. Missing or incorrect required parameters
Symptom: The API returns an error indicating a missing parameter, or the response contains unexpected data.
Solution: Each endpoint has specific required parameters (e.g., lat, lng, rad for the /list endpoint). Consult the Tankerkoenig API documentation for the endpoint you are calling and ensure all mandatory parameters are included and correctly formatted. For example, latitude and longitude should be valid decimal numbers.
4. Exceeded request limits
Symptom: The API returns an error message related to quota exceeded or too many requests. Solution: The free tier is limited to 50 requests per day. If you are developing and testing frequently, you might hit this limit. Wait until the next day for your quota to reset, or consider upgrading your Tankerkoenig plan if higher usage is consistently required.
5. Network or connectivity issues
Symptom: Your request times out, or you receive a network error from your client (e.g., cURL, browser).
Solution: Check your internet connection. Try accessing other websites to confirm connectivity. If you are behind a corporate firewall or proxy, ensure that outgoing connections to creativecommons.tankerkoenig.de are allowed. Tools like ping or traceroute can help diagnose network path issues (Microsoft Ping documentation).
6. Incorrect JSON parsing
Symptom: Your application fails to read data from a seemingly successful API response.
Solution: Ensure your application's JSON parser is correctly implemented. Use a JSON validator tool to inspect the raw API response and confirm it is well-formed. Libraries like json in Python or JSON.parse() in JavaScript are designed for this purpose (MDN JSON.parse() documentation).