Alle FlowData-Bereiche funktionieren nach demselben Muster: eine HTTPS-Anfrage an https://api.flowdata.one/v1/... mit deinem Schlüssel im Header Authorization: Bearer fd_.... Hier findest du fertige Beispiele für PHP, Node.js und Python, die du direkt übernehmen kannst. Jedes Beispiel zeigt eine einfache Abfrage und eine Anfrage mit JSON-Body.
Den Schlüssel sicher ablegen
Schreib den Schlüssel nie direkt in den Quelltext und nie in Code, der im Browser läuft. Leg ihn als Umgebungsvariable auf deinem Server ab, zum Beispiel als FLOWDATA_KEY, und lies ihn im Programm aus. So landet er weder in deinem Git-Repository noch bei Besuchern deiner Website. Wie du einen Schlüssel anlegst, steht in FlowData-API-Schlüssel anlegen.
PHP
Das Beispiel kommt ohne zusätzliche Pakete aus und nutzt die cURL-Erweiterung von PHP.
<?php
function flowdata(string $method, string $path, ?array $body = null): array
{
$ch = curl_init('https://api.flowdata.one/v1/' . $path);
$headers = [
'Authorization: Bearer ' . getenv('FLOWDATA_KEY'),
'Accept: application/json',
];
if ($body !== null) {
$headers[] = 'Content-Type: application/json';
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($body));
}
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => $method,
CURLOPT_HTTPHEADER => $headers,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_TIMEOUT => 30,
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
return ['status' => $status, 'data' => json_decode((string) $response, true)];
}
$geo = flowdata('GET', 'geolocation/' . rawurlencode('8.8.8.8') . '?lang=de');
$batch = flowdata('POST', 'geolocation/batch', ['8.8.8.8', '1.1.1.1']);
if ($geo['status'] === 200) {
echo $geo['data']['country'] ?? 'unknown';
}
Node.js
Ab Node.js 18 ist fetch eingebaut, du brauchst kein zusätzliches Paket.
async function flowdata(method, path, body) {
const response = await fetch(`https://api.flowdata.one/v1/${path}`, {
method,
headers: {
Authorization: `Bearer ${process.env.FLOWDATA_KEY}`,
Accept: 'application/json',
...(body ? { 'Content-Type': 'application/json' } : {}),
},
body: body ? JSON.stringify(body) : undefined,
signal: AbortSignal.timeout(30000),
});
return { status: response.status, data: await response.json() };
}
const geo = await flowdata('GET', `geolocation/${encodeURIComponent('8.8.8.8')}?lang=de`);
const batch = await flowdata('POST', 'geolocation/batch', ['8.8.8.8', '1.1.1.1']);
if (geo.status === 200) {
console.log(geo.data.country);
}
Speichere die Datei mit der Endung .mjs, damit await außerhalb einer Funktion erlaubt ist.
Python
Das Beispiel nutzt das verbreitete Paket requests.
import os
import requests
BASE = "https://api.flowdata.one/v1/"
HEADERS = {
"Authorization": f"Bearer {os.environ['FLOWDATA_KEY']}",
"Accept": "application/json",
}
def flowdata(method, path, body=None):
response = requests.request(method, BASE + path, headers=HEADERS, json=body, timeout=30)
return response.status_code, response.json()
status, geo = flowdata("GET", "geolocation/8.8.8.8?lang=de")
status_batch, batch = flowdata("POST", "geolocation/batch", ["8.8.8.8", "1.1.1.1"])
if status == 200:
print(geo.get("country"))
Mit json=body setzt requests den Header Content-Type: application/json automatisch.
Andere Bereiche aufrufen
Für die übrigen Bereiche tauschst du nur den Pfad aus:
| Bereich | Pfad |
|---|---|
| Client Info | GET client-info |
| Maps | GET maps/search?q=..., GET maps/geocode?address=..., GET maps/directions?origin=...&destination=... |
| Email Verifier | GET email-verification/ plus URL-kodierte Adresse |
| YouTube | GET youtube/stats/ plus Handle oder Kanal-ID |
| Medienverarbeitung | POST media/jobs mit JSON-Body, GET media/jobs |
Kodiere Werte in der Adresse immer für die URL: in PHP mit rawurlencode(), in JavaScript mit encodeURIComponent(), in Python mit urllib.parse.quote().
Mit 402 und 429 umgehen
Antwortet FlowData mit HTTP 429, hat dein Schlüssel zu viele Anfragen pro Minute gestellt. Warte die Sekunden aus dem Header Retry-After ab und versuch es dann erneut. Schick nicht sofort und in einer Schleife neue Anfragen, bis die Minute um ist, werden sie ohnehin abgelehnt.
HTTP 402 bedeutet, dass das Guthaben oder ein Ausgabenlimit nicht reicht. Hier hilft kein erneuter Versuch, bis jemand Guthaben auflädt oder das Limit anhebt. Alle Fehlermeldungen im Überblick stehen in Fehlermeldungen und Anfragelimits.
Gut zu wissen
- Prüfe immer zuerst den HTTP-Status und erst dann den Inhalt der Antwort.
- Setz einen großzügigen Timeout. Die erste Prüfung einer E-Mail-Adresse oder eines YouTube-Kanals dauert länger als eine gespeicherte.
- Jede Anfrage erscheint im Protokoll des Bereichs. Beim Einrichten siehst du dort sofort, ob deine Integration richtig fragt.
- Vor dem ersten Einbau kannst du Anfragen im Playground ausprobieren.