FlowData

Como chamar o FlowData em PHP, JavaScript ou Python?

Publicado em 10. novembro 2026

Todas as áreas do FlowData seguem o mesmo padrão: uma requisição HTTPS para https://api.flowdata.one/v1/... com sua chave no cabeçalho Authorization: Bearer fd_.... Aqui você encontra exemplos prontos em PHP, Node.js e Python. Cada um mostra uma consulta simples e uma requisição com corpo JSON.

Guardar a chave com segurança

Nunca escreva a chave diretamente no código-fonte nem em código que rode no navegador. Guarde-a como variável de ambiente no seu servidor, por exemplo FLOWDATA_KEY, e leia o valor no programa. Assim ela não vai parar no seu repositório Git nem chega aos visitantes do seu site. Veja como obter uma chave em Criar uma chave de API do FlowData.

PHP

Este exemplo não precisa de pacotes adicionais e usa a extensão cURL do 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

A partir do Node.js 18, o fetch já vem embutido, então você não precisa de pacote adicional.

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);
}

Salve o arquivo com a extensão .mjs para poder usar await fora de uma função.

Python

Este exemplo usa o conhecido pacote 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"))

Com json=body, o requests define o cabeçalho Content-Type: application/json automaticamente.

Chamar outras áreas

Para as demais áreas, basta trocar o caminho:

Área Caminho
Client Info GET client-info
Maps GET maps/search?q=..., GET maps/geocode?address=..., GET maps/directions?origin=...&destination=...
Email Verifier GET email-verification/ mais o endereço codificado para URL
YouTube GET youtube/stats/ mais o handle ou o ID do canal
Processamento de mídia POST media/jobs com corpo JSON, GET media/jobs

Sempre codifique os valores no endereço para URL: em PHP com rawurlencode(), em JavaScript com encodeURIComponent() e em Python com urllib.parse.quote().

Como lidar com 402 e 429

Se o FlowData responder com HTTP 429, sua chave fez requisições demais por minuto. Aguarde os segundos indicados no cabeçalho Retry-After e tente novamente. Não envie novas requisições imediatamente em um laço, pois elas serão recusadas de qualquer forma até o minuto acabar.

HTTP 402 significa que o saldo ou um limite de gastos não é suficiente. Repetir não adianta até alguém recarregar o saldo ou aumentar o limite. Todas as mensagens de erro estão em Erros e limites de requisições.

Bom saber

  • Verifique sempre primeiro o status HTTP e só depois o conteúdo da resposta.
  • Defina um timeout generoso. A primeira verificação de um endereço de e-mail ou canal do YouTube demora mais do que uma já armazenada.
  • Cada requisição aparece no registro da respectiva área, então durante a configuração você vê na hora se sua integração está chamando corretamente.
  • Antes de integrar, você pode testar requisições no Playground.

Este artigo foi útil?

Voltar para Primeiros passos e chaves de API