### API Error Response Example

Source: https://creativecommons.tankerkoenig.de/

This JSON structure illustrates a typical error response from the API. Always check the 'ok' flag to ensure successful requests and handle errors appropriately.

```json
{
  "ok":false,
  "message":"parameter error"
}
```

--------------------------------

### API Key Usage Example

Source: https://creativecommons.tankerkoenig.de/

This JavaScript snippet demonstrates how to declare an API key for accessing the Tankerkönig API. Remember to replace the placeholder with your actual key and consider adding comments for clarity.

```javascript
// Key für den Zugriff auf die freie Tankerkönig-Spritpreis-API
// Für eigenen Key bitte hier https://creativecommons.tankerkoenig.de
// registrieren.
var tankerkoenig_api_key = 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'; // TODO: Key ersetzen
```

--------------------------------

### Detailabfrage

Source: https://creativecommons.tankerkoenig.de/

Mit der Detail-Abfrage werden einige wenige Informationen geliefert, die in der Antwort der Umkreissuche nicht enthalten sind: `detail.php`. Ein Aufruf dieser Funktion ist für Apps sinnvoll, wenn dem User Details einer ausgewählten Tankstelle angezeigt werden sollen.

```APIDOC
## GET detail.php

### Description
Liefert detaillierte Informationen zu einer spezifischen Tankstelle, die über die Umkreissuche nicht verfügbar sind.

### Method
GET

### Endpoint
/json/detail.php

### Parameters
#### Query Parameters
- **id** (UUID) - Required - Die ID der Tankstelle.
- **apikey** (UUID) - Required - Der persönliche API-Key.

### Request Example
```
https://creativecommons.tankerkoenig.de/json/detail.php?id=24a381e3-0d72-416d-bfd8-b2f65f6e5802&apikey=00000000-0000-0000-0000-000000000002
```

### Response
#### Success Response (200)
- **ok** (boolean) - Gibt an, ob die Anfrage erfolgreich war.
- **license** (string) - Lizenzinformationen der API.
- **data** (string) - Datenquelle (z.B. "MTS-K").
- **status** (string) - Status der Anfrage (z.B. "ok").
- **station** (object) - Ein Objekt, das die Tankstellendetails enthält:
  - **id** (string) - Die ID der Tankstelle.
  - **name** (string) - Der Name der Tankstelle.
  - **brand** (string) - Die Marke der Tankstelle.
  - **street** (string) - Die Straße der Tankstelle.
  - **houseNumber** (string) - Die Hausnummer.
  - **postCode** (integer) - Die Postleitzahl.
  - **place** (string) - Der Ort.
  - **openingTimes** (array) - Ein Array von Objekten, die die regulären Öffnungszeiten beschreiben.
    - **text** (string) - Beschreibung des Zeitraums (z.B. "Mo-Fr").
    - **start** (string) - Startzeit (HH:MM:SS).
    - **end** (string) - Endzeit (HH:MM:SS).
  - **overrides** (array) - Ein Array von Strings, die Änderungen der regulären Öffnungszeiten beschreiben (z.B. temporäre Schließungen).
  - **wholeDay** (boolean) - Gibt an, ob die Tankstelle ganztägig geöffnet ist.
  - **isOpen** (boolean) - Gibt an, ob die Tankstelle aktuell geöffnet ist.
  - **e5** (float) - Preis für E5 Benzin.
  - **e10** (float) - Preis für E10 Benzin.
  - **diesel** (float) - Preis für Diesel.
  - **lat** (float) - Breitengrad.
  - **lng** (float) - Längengrad.
  - **state** (string|null) - Das Bundesland (Kürzel), falls angegeben.

#### Response Example
```json
{
    "ok": true,
    "license": "CC BY 4.0 -  https:\/\/creativecommons.tankerkoenig.de",
    "data": "MTS-K",
    "status": "ok",
    "station": {
        "id": "24a381e3-0d72-416d-bfd8-b2f65f6e5802",
        "name": "Esso Tankstelle",
        "brand": "ESSO",
        "street": "HAUPTSTR. 7",
        "houseNumber": " ",
        "postCode": 84152,
        "place": "MENGKOFEN",
        "openingTimes": [
            {
                "text": "Mo-Fr",
                "start": "06:00:00",
                "end": "22:30:00"
            },
            {
                "text": "Samstag",
                "start": "07:00:00",
                "end": "22:00:00"
            },
            {
                "text": "Sonntag",
                "start": "08:00:00",
                "end": "22:00:00"
            }
        ],
        "overrides": [
            "13.04.2017, 15:00:00 - 13.11.2017, 15:00:00: geschlossen"
        ],
        "wholeDay": false,
        "isOpen": false,
        "e5": 1.379,
        "e10": 1.359,
        "diesel": 1.169,
        "lat": 48.72210601,
        "lng": 12.44438439,
        "state": null
    }
}
```
```

--------------------------------

### General API Request Information

Source: https://creativecommons.tankerkoenig.de/

All API methods require an API key. Responses include an 'ok' flag to indicate success or failure, along with an error message if applicable. It is recommended to always check the 'ok' flag.

```APIDOC
## Requests allgemein
In jedem Aufruf einer API-Methode muss ein API-Key mit angegeben werden.   
Die Antwort enthält immer ein `ok` flag, dessen Status abgefragt werden sollte. Im Fehlerfall (ok == false) enthält die Antwort einen Text mit der Fehlerursache, bspw: 
```
{
  "ok":false,
  "message":"parameter error"
}

```
Es ist sinnvoll und dringend empfohlen, immer das ok-Flag abzufragen um zu testen, ob der Aufruf erfolgreich war.   
Je nach Applikation sollte der Fehler entsprechend behandelt werden, etwa so: 
  * Fehlertext anzeigen,
  * Fehlertext an Server melden, falls ein eigener Server eingesetzt wird,
  * Keine weiteren Requests mehr senden
```

--------------------------------

### Beispielantwort der Detailabfrage

Source: https://creativecommons.tankerkoenig.de/

Stellt die Struktur der Antwort für eine Detailabfrage dar, einschließlich regulärer und geänderter Öffnungszeiten sowie weiterer Tankstelleninformationen.

```JSON
{
    "ok": true,
    "license": "CC BY 4.0 -  https:\/\/creativecommons.tankerkoenig.de",
    "data": "MTS-K",
    "status": "ok",
    "station": {
        "id": "24a381e3-0d72-416d-bfd8-b2f65f6e5802",
        "name": "Esso Tankstelle",
        "brand": "ESSO",
        "street": "HAUPTSTR. 7",
        "houseNumber": " ",
        "postCode": 84152,
        "place": "MENGKOFEN",
        "openingTimes": [
            {
                "text": "Mo-Fr",
                "start": "06:00:00",
                "end": "22:30:00"
            },
            {
                "text": "Samstag",
                "start": "07:00:00",
                "end": "22:00:00"
            },
            {
                "text": "Sonntag",
                "start": "08:00:00",
                "end": "22:00:00"
            }
        ],
        "overrides": [
            "13.04.2017, 15:00:00 - 13.11.2017, 15:00:00: geschlossen"
        ],
        "wholeDay": false,
        "isOpen": false,
        "e5": 1.379,
        "e10": 1.359,
        "diesel": 1.169,
        "lat": 48.72210601,
        "lng": 12.44438439,
        "state": null
    }
}
```

--------------------------------

### Umkreissuche

Source: https://creativecommons.tankerkoenig.de/

Ruft Tankstelleninformationen und Preise für Tankstellen in einem angegebenen Radius um einen Standort ab.

```APIDOC
## GET list.php

### Description
Ruft Tankstelleninformationen und Preise für Tankstellen in einem angegebenen Radius um einen Standort ab.

### Method
GET

### Endpoint
/json/list.php

### Parameters
#### Query Parameters
- **lat** (Floatingpoint-Zahl) - Required - Geographische Breite des Standortes
- **lng** (Floatingpoint-Zahl) - Required - Geographische Länge
- **rad** (Floatingpoint-Zahl) - Required - Suchradius in km, max: 25
- **type** (string) - Optional - Spritsorte: 'e5', 'e10', 'diesel' oder 'all'
- **sort** (string) - Optional - Sortierung: 'price' oder 'dist'. Bei type=all wird immer nach Entfernung sortiert.
- **apikey** (UUID) - Required - Der persönliche API-Key

### Request Example
https://creativecommons.tankerkoenig.de/json/list.php?lat=52.521&lng=13.438&rad=1.5&sort=dist&type=all&apikey=00000000-0000-0000-0000-000000000002

### Response
#### Success Response (200)
- **ok** (boolean) - Gibt an, ob die Anfrage erfolgreich war.
- **license** (string) - Lizenzinformationen.
- **data** (string) - Datenkennung.
- **stations** (array) - Eine Liste von Tankstellenobjekten.
  - **id** (UUID) - Eindeutige Tankstellen-ID.
  - **name** (string) - Name der Tankstelle.
  - **brand** (string) - Marke der Tankstelle.
  - **street** (string) - Straße der Tankstelle.
  - **place** (string) - Ort der Tankstelle.
  - **lat** (float) - Geographische Breite.
  - **lng** (float) - Geographische Länge.
  - **dist** (float) - Entfernung zum Suchstandort in km.
  - **diesel** (float) - Preis für Diesel.
  - **e5** (float) - Preis für E5.
  - **e10** (float) - Preis für E10.
  - **isOpen** (boolean) - Gibt an, ob die Tankstelle geöffnet ist.
  - **houseNumber** (string) - Hausnummer.
  - **postCode** (integer) - Postleitzahl.

#### Response Example
{
    "ok": true,
    "license": "CC BY 4.0 -  https:\/\/creativecommons.tankerkoenig.de",
    "data": "MTS-K",
    "status": "ok",
    "stations": [
        {
            "id": "474e5046-deaf-4f9b-9a32-9797b778f047",
            "name": "TOTAL BERLIN",
            "brand": "TOTAL",
            "street": "MARGARETE-SOMMER-STR.",
            "place": "BERLIN",
            "lat": 52.53083,
            "lng": 13.440946,
            "dist": 1.1,
            "diesel": 1.109,
            "e5": 1.339,
            "e10": 1.319,
            "isOpen": true,
            "houseNumber": "2",
            "postCode": 10407
        }
    ]
}
```

--------------------------------

### Preisabfrage

Source: https://creativecommons.tankerkoenig.de/

Ruft die Preise von bis zu 10 bekannten Tankstellen gleichzeitig ab.

```APIDOC
## GET prices.php

### Description
Ruft die Preise von bis zu 10 bekannten Tankstellen gleichzeitig ab.

### Method
GET

### Endpoint
/json/prices.php

### Parameters
#### Query Parameters
- **ids** (string) - Required - IDs der Tankstellen, durch Komma getrennt.
- **apikey** (UUID) - Required - Der persönliche API-Key.

### Request Example
https://creativecommons.tankerkoenig.de/json/prices.php?ids=4429a7d9-fb2d-4c29-8cfe-2ca90323f9f8,446bdcf5-9f75-47fc-9cfa-2c3d6fda1c3b,60c0eefa-d2a8-4f5c-82cc-b5244ecae955,44444444-4444-4444-4444-444444444444&apikey=00000000-0000-0000-0000-000000000002

### Response
#### Success Response (200)
- **ok** (boolean) - Gibt an, ob die Anfrage erfolgreich war.
- **license** (string) - Lizenzinformationen.
- **data** (string) - Datenkennung.
- **prices** (object) - Ein Objekt, das die Preise für jede angefragte Tankstelle enthält.
  - **[Tankstellen-ID]** (object) - Ein Objekt mit den Preisinformationen für eine spezifische Tankstelle.
    - **status** (string) - Status der Tankstelle ('open', 'closed', 'no prices').
    - **e5** (float or boolean) - Preis für E5 oder false, wenn nicht verfügbar.
    - **e10** (float or boolean) - Preis für E10 oder false, wenn nicht verfügbar.
    - **diesel** (float or boolean) - Preis für Diesel oder false, wenn nicht verfügbar.

#### Response Example
{
    "ok": true,
    "license": "CC BY 4.0 -  https:\/\/creativecommons.tankerkoenig.de",
    "data": "MTS-K",
    "prices": {
        "60c0eefa-d2a8-4f5c-82cc-b5244ecae955": {
            "status": "open",
            "e5": false,
            "e10": false,
            "diesel": 1.189
        },
        "446bdcf5-9f75-47fc-9cfa-2c3d6fda1c3b": {
            "status": "closed"
        },
        "4429a7d9-fb2d-4c29-8cfe-2ca90323f9f8": {
            "status": "open",
            "e5": 1.409,
            "e10": 1.389,
            "diesel": 1.129
        },
        "44444444-4444-4444-4444-444444444444": {
            "status": "no prices"
        }
    }
}
```

--------------------------------

### Price Query Response Structure

Source: https://creativecommons.tankerkoenig.de/

This JSON structure represents the response from the price query API. It provides pricing and status information for the requested gas stations.

```JSON
{
    "ok": true,
    "license": "CC BY 4.0 -  https:\/\/creativecommons.tankerkoenig.de",
    "data": "MTS-K",
    "prices": {
        "60c0eefa-d2a8-4f5c-82cc-b5244ecae955": {
            "status": "open",
            "e5": false,
            "e10": false,
            "diesel": 1.189
        },
        "446bdcf5-9f75-47fc-9cfa-2c3d6fda1c3b": {
            "status": "closed"
        },
        "4429a7d9-fb2d-4c29-8cfe-2ca90323f9f8": {
            "status": "open",
            "e5": 1.409,
            "e10": 1.389,
            "diesel": 1.129
        },
        "44444444-4444-4444-4444-444444444444": {
            "status": "no prices"
        }
    }
}
```

--------------------------------

### Successful Complaint Response

Source: https://creativecommons.tankerkoenig.de/

This is the expected JSON response when a complaint is successfully processed.

```json
{
    "ok": true
}
```

--------------------------------

### Gas Station Price Query API Call

Source: https://creativecommons.tankerkoenig.de/

Use this URL to query prices for up to 10 specific gas stations using their IDs. Requires a comma-separated list of station IDs and your API key.

```HTTP
https://creativecommons.tankerkoenig.de/json/prices.php?ids=4429a7d9-fb2d-4c29-8cfe-2ca90323f9f8,446bdcf5-9f75-47fc-9cfa-2c3d6fda1c3b,60c0eefa-d2a8-4f5c-82cc-b5244ecae955,44444444-4444-4444-4444-444444444444&apikey=00000000-0000-0000-0000-000000000002
```

--------------------------------

### Detailabfrage einer Tankstelle

Source: https://creativecommons.tankerkoenig.de/

Ruft detaillierte Informationen zu einer spezifischen Tankstelle ab. Erfordert die ID der Tankstelle und einen API-Schlüssel. Diese Methode ist nicht für regelmäßige Preisabfragen gedacht.

```HTTP
https://creativecommons.tankerkoenig.de/json/detail.php?id=24a381e3-0d72-416d-bfd8-b2f65f6e5802&apikey=00000000-0000-0000-0000-000000000002
```

--------------------------------

### Send Complaint with jQuery

Source: https://creativecommons.tankerkoenig.de/

Use this function to send error reports for a specific gas station. Ensure the complaint type is valid and provide a correction if applicable. The demo key is for testing only and requests are not forwarded.

```javascript
function sendComplaint(stationId, complaintType, correction){
    var apikey = '00000000-0000-0000-0000-000000000002'; // Demo-Key nur zum Testen, diese Requests werden nicht weitergegeben

    var data = {
        apikey: apikey,
        id: stationId,
        type: complaintType
    };

    if (correction) {
        data.correction = correction;
    }

    $.ajax({
        url: "https://creativecommons.tankerkoenig.de/json/complaint.php",
        method: 'POST',
        data: data,
        success: function( response ) {
            if (!response.ok) {
                alert(response.message);
            } else {
                alert('Meldung erfolgreich übertragen');
            }
        }
    });
}

var stationId = 'd3f68a43-e249-4a1f-bd34-0023677cdcc9';

// Test 1
sendComplaint(stationId, 'wrongStatusClosed', null);    // keine Korrekturangabe erlaubt

// Test 2
sendComplaint(stationId, 'wrongPriceDiesel', 1.234);

// Test 3
sendComplaint(stationId, 'wrongPetrolStationLocation', '52.29162,10.06117');

// Test 4
sendComplaint(stationId, 'illegal token', '52.29162,10.06117');
                    
```

--------------------------------

### Report an Error

Source: https://creativecommons.tankerkoenig.de/

This method allows users to report errors related to gas station information, such as incorrect names, status, prices, or location. It requires a station ID, an API key, and the type of error. An optional correction parameter can be provided for specific error types.

```APIDOC
## POST complaint.php

### Description
Allows users to report errors related to gas station information.

### Method
POST

### Endpoint
https://creativecommons.tankerkoenig.de/json/complaint.php

### Parameters
#### Path Parameters
None

#### Query Parameters
- **apikey** (UUID) - Required - The personal API key.
- **id** (UUID) - Required - The ID of the gas station.
- **type** (string) - Required - The type of error being reported. See error types below.
- **correction** (string) - Optional - The corrected value for the reported error. This is only applicable for certain error types.

#### Request Body
This endpoint does not use a request body; parameters are sent as form data.

### Request Example
```javascript
function sendComplaint(stationId, complaintType, correction){
    var apikey = 'YOUR_API_KEY'; // Replace with your actual API key

    var data = {
        apikey: apikey,
        id: stationId,
        type: complaintType
    };

    if (correction) {
        data.correction = correction;
    }

    $.ajax({
        url: "https://creativecommons.tankerkoenig.de/json/complaint.php",
        method: 'POST',
        data: data,
        success: function( response ) {
            if (!response.ok) {
                console.error(response.message);
            } else {
                console.log('Meldung erfolgreich übertragen');
            }
        }
    });
}

var stationId = 'd3f68a43-e249-4a1f-bd34-0023677cdcc9';

// Example: Report a closed station with no correction
sendComplaint(stationId, 'wrongStatusClosed', null);

// Example: Report an incorrect Diesel price with correction
sendComplaint(stationId, 'wrongPriceDiesel', 1.234);

// Example: Report incorrect location coordinates
sendComplaint(stationId, 'wrongPetrolStationLocation', '52.29162,10.06117');
```

### Response
#### Success Response (200)
- **ok** (boolean) - Indicates if the report was successful.

#### Error Response
- **ok** (boolean) - Indicates if the report failed.
- **message** (string) - Description of the error.

#### Response Example (Success)
```json
{
    "ok": true
}
```

#### Response Example (Error)
```json
{
    "ok": false,
    "message": "Meldungstyp 'illegal token' nicht erlaubt"
}
```

### Error Types
- **wrongPetrolStationName**: The name is incorrect. Correction: provide the correct name.
- **wrongStatusOpen**: The station is open, but should be closed according to opening hours. Correction is not applicable.
- **wrongStatusClosed**: The station is closed, but should be open according to opening hours. Correction is not applicable.
- **wrongPriceE5**: Incorrect price for E5. Correction: provide the correct floating-point value.
- **wrongPriceE10**: Incorrect price for E10. Correction: provide the correct floating-point value.
- **wrongPriceDiesel**: Incorrect price for Diesel. Correction: provide the correct floating-point value.
- **wrongPetrolStationBrand**: The brand is incorrect. Correction: provide the correct brand name.
- **wrongPetrolStationStreet**: The street name is incorrect. Correction: provide the correct street name.
- **wrongPetrolStationHouseNumber**: The house number is incorrect. Correction: provide the correct house number.
- **wrongPetrolStationPostcode**: The postcode is incorrect. Correction: provide the correct postcode.
- **wrongPetrolStationPlace**: The place name is incorrect. Correction: provide the correct place name.
- **wrongPetrolStationLocation**: The geocoordinates are incorrect. Correction: provide two comma-separated floating-point numbers for latitude and longitude.

* **Note**: Only the specified error types are allowed. Only corrections are permitted, no annotations. Only one error can be reported per message. A syntactic check is performed, not a content check.
```

--------------------------------

### Gas Station Radius Search API Call

Source: https://creativecommons.tankerkoenig.de/

Use this URL to find gas stations and their prices within a given radius. Parameters include latitude, longitude, radius, fuel type, sorting preference, and your API key.

```HTTP
https://creativecommons.tankerkoenig.de/json/list.php?lat=52.521&lng=13.438&rad=1.5&sort=dist&type=all&apikey=00000000-0000-0000-0000-000000000002
```

--------------------------------

### Error Complaint Response

Source: https://creativecommons.tankerkoenig.de/

This is the JSON response when a complaint fails due to an invalid error type.

```json
{
    "ok": false,
    "message": "Meldungstyp 'illegal token' nicht erlaubt"
}
```

--------------------------------

### Radius Search Response Structure

Source: https://creativecommons.tankerkoenig.de/

This JSON structure represents the response from the radius search API. It includes general information and a list of stations with their details and prices.

```JSON
{
    "ok": true,
    "license": "CC BY 4.0 -  https:\/\/creativecommons.tankerkoenig.de",
    "data": "MTS-K",
    "status": "ok",
    "stations": [
        {
            "id": "474e5046-deaf-4f9b-9a32-9797b778f047",
            "name": "TOTAL BERLIN",
            "brand": "TOTAL",
            "street": "MARGARETE-SOMMER-STR.",
            "place": "BERLIN",
            "lat": 52.53083,
            "lng": 13.440946,
            "dist": 1.1,
            "diesel": 1.109,
            "e5": 1.339,
            "e10": 1.319,
            "isOpen": true,
            "houseNumber": "2",
            "postCode": 10407
        },
        ... weitere Tankstellen
    ]
}
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.