FlowData

How do I call FlowData from PHP, JavaScript or Python?

Published on 10. November 2026

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.

Was this article helpful?

Back to Getting started & API keys