Começando

Aprenda como integrar as APIs NetFind.io em sua aplicação.

Início Rápido

1. Faça sua Primeira Requisição

curl "https://api.netfind.io/api/search-and-scrape?q=hello+world"

2. Parse a Resposta

const response = await fetch('/api/search-and-scrape?q=hello+world');
const data = await response.json();

console.log(`Encontrados ${data.results.length} resultados`);

for (const result of data.results) {
  console.log(`${result.title}: ${result.url}`);
}

Endpoints Disponíveis

Endpoint	Método	Descrição
/api/search-and-scrape	GET	Busca web com extração de conteúdo
/v1/search/hybrid	POST	Busca combinada web + documentos
/api/search-startpage	GET	Busca Startpage focada em privacidade

Padrões Comuns

Tratamento de Erros

Sempre trate possíveis erros:

async function search(query) {
  try {
    const response = await fetch(`/api/search-and-scrape?q=${encodeURIComponent(query)}`);

    if (!response.ok) {
      const error = await response.json();
      throw new Error(error.detail || error.error);
    }

    return response.json();
  } catch (error) {
    console.error('Busca falhou:', error.message);
    throw error;
  }
}

Retry com Backoff

Para aplicações em produção:

async function searchWithRetry(query, maxRetries = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    try {
      const response = await fetch(`/api/search-and-scrape?q=${encodeURIComponent(query)}`);
      if (response.ok) return response.json();

      // Não fazer retry em erros de cliente
      if (response.status < 500) {
        throw new Error(`Requisição falhou: ${response.status}`);
      }
    } catch (error) {
      if (attempt === maxRetries - 1) throw error;

      // Exponential backoff
      const delay = Math.pow(2, attempt) * 1000;
      await new Promise(r => setTimeout(r, delay));
    }
  }
}

Cache de Respostas

A API já implementa cache multi-camada, mas você pode adicionar cache client-side:

const cache = new Map();
const CACHE_TTL = 5 * 60 * 1000; // 5 minutos

async function cachedSearch(query) {
  const cacheKey = query.toLowerCase().trim();
  const cached = cache.get(cacheKey);

  if (cached && Date.now() - cached.timestamp < CACHE_TTL) {
    return cached.data;
  }

  const data = await search(query);
  cache.set(cacheKey, { data, timestamp: Date.now() });

  return data;
}

Exemplos de Integração

Hook React

import { useState, useEffect } from 'react';

function useSearch(query) {
  const [results, setResults] = useState([]);
  const [loading, setLoading] = useState(false);
  const [error, setError] = useState(null);

  useEffect(() => {
    if (!query) {
      setResults([]);
      return;
    }

    const controller = new AbortController();
    setLoading(true);
    setError(null);

    fetch(`/api/search-and-scrape?q=${encodeURIComponent(query)}`, {
      signal: controller.signal
    })
      .then(r => r.json())
      .then(data => setResults(data.results || []))
      .catch(err => {
        if (err.name !== 'AbortError') {
          setError(err.message);
        }
      })
      .finally(() => setLoading(false));

    return () => controller.abort();
  }, [query]);

  return { results, loading, error };
}

Serviço Node.js

import { setTimeout } from 'timers/promises';

class SearchService {
  constructor(baseUrl) {
    this.baseUrl = baseUrl;
    this.rateLimitDelay = 100; // ms entre requisições
    this.lastRequest = 0;
  }

  async search(query, options = {}) {
    // Rate limiting
    const now = Date.now();
    const elapsed = now - this.lastRequest;
    if (elapsed < this.rateLimitDelay) {
      await setTimeout(this.rateLimitDelay - elapsed);
    }
    this.lastRequest = Date.now();

    const params = new URLSearchParams({
      q: query,
      limit: String(options.limit || 5)
    });

    const response = await fetch(`${this.baseUrl}/api/search-and-scrape?${params}`);

    if (!response.ok) {
      throw new Error(`Busca falhou: ${response.status}`);
    }

    return response.json();
  }
}

// Uso
const search = new SearchService('https://api.netfind.io');
const results = await search.search('typescript tutorial', { limit: 10 });

Cliente Python

import requests
from time import sleep
from functools import lru_cache

class NetFindClient:
    def __init__(self, base_url="https://api.netfind.io"):
        self.base_url = base_url
        self.session = requests.Session()

    def search(self, query: str, limit: int = 5) -> dict:
        response = self.session.get(
            f"{self.base_url}/api/search-and-scrape",
            params={"q": query, "limit": limit},
            timeout=10
        )
        response.raise_for_status()
        return response.json()

    def search_with_retry(self, query: str, max_retries: int = 3) -> dict:
        for attempt in range(max_retries):
            try:
                return self.search(query)
            except requests.RequestException as e:
                if attempt == max_retries - 1:
                    raise
                sleep(2 ** attempt)

# Uso
client = NetFindClient()
results = client.search("machine learning", limit=10)
print(f"Encontrados {len(results['results'])} resultados")

Próximos Passos

• Referência: Search and Scrape
• Limites de Taxa