All FlowData areas follow the same pattern: an HTTPS request to https://api.flowdata.one/v1/... with your key in the Authorization: Bearer fd_... header. Below you'll find ready-to-use samples for PHP, Node.js and Python. Each one shows a simple lookup and a request with a JSON body.
Storing the key safely
Never write the key directly into your source code or into code that runs in the browser. Store it as an environment variable on your server, for example as FLOWDATA_KEY, and read it in your program. That way it ends up neither in your Git repository nor with visitors to your website. Creating a FlowData API key explains how to get one.
PHP
This sample needs no extra packages and uses PHP's cURL extension.
<?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
fetch is built in from Node.js 18 on, so you don't need an extra package.
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);
}
Save the file with the .mjs extension so that await is allowed outside a function.
Python
This sample uses the popular requests package.
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"))
With json=body, requests sets the Content-Type: application/json header automatically.
Calling other areas
For the remaining areas you only swap the path:
| Area | Path |
|---|---|
| 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 the URL-encoded address |
| YouTube | GET youtube/stats/ plus the handle or channel ID |
| Media processing | POST media/jobs with a JSON body, GET media/jobs |
Always URL-encode values in the address: with rawurlencode() in PHP, encodeURIComponent() in JavaScript and urllib.parse.quote() in Python.
Handling 402 and 429
If FlowData answers with HTTP 429, your key has sent too many requests per minute. Wait for the number of seconds in the Retry-After header and then try again. Don't send new requests immediately in a loop, because they'll be refused until the minute is over anyway.
HTTP 402 means the balance or a spend limit isn't enough. Retrying won't help until someone tops up the balance or raises the limit. All error messages are listed in Errors and rate limits.
Good to know
- Always check the HTTP status first and only then the content of the response.
- Set a generous timeout. The first check of an email address or YouTube channel takes longer than a stored one.
- Every request appears in the log of its area, so you can see right away during setup whether your integration is asking correctly.
- Before you build anything in, you can try out requests in the Playground.