Templates

Introdução

Templates são configurações reutilizáveis para scraping, crawling ou busca. Em vez de repetir as mesmas opções em cada chamada, você define uma vez em um template (ou obtém um na AnyCrawl Template Store) e referencia com template_id.

Benefícios:

• Simplicidade: chame a API só com template_id + entradas mínimas
• Consistência: padronize o comportamento na equipe ou nos projetos
• Segurança: templates podem restringir domínios e expor apenas variáveis necessárias
• Poder: handlers opcionais para transformações avançadas

Tipos suportados:

• scrape: extração de página única via /v1/scrape
• crawl: crawling multi-página via /v1/crawl
• search: resultados de mecanismos de busca via /v1/search

Marketplace de templates

Explore templates prontos em anycrawl.dev/template.

Como usar:

1. Navegue no marketplace e encontre um template adequado
2. Copie o template_id na página de detalhes
3. Chame a API com esse template_id e as entradas necessárias

Exemplo:

curl -X POST "https://api.anycrawl.dev/v1/scrape" \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "template_id": "content-extractor",
    "url": "https://example.com"
  }'

Uso de templates nas chamadas da API

Parâmetros da requisição

Com template_id, só campos mínimos são permitidos:

Observações importantes:

• url ou query podem ser opcionais se o template já os definir. Consulte a descrição do template.
• variables passa entradas dinâmicas que o template espera (veja a seção Variáveis).
• Outros campos (engine, formats, timeout etc.) vêm do template e não podem ser sobrescritos.
• Campos não permitidos retornam erro de validação 400.

Scrape com template

curl -X POST "https://api.anycrawl.dev/v1/scrape" \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "template_id": "my-scrape-template",
    "url": "https://example.com",
    "variables": { "category": "tech" }
  }'

Crawl com template

curl -X POST "https://api.anycrawl.dev/v1/crawl" \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "template_id": "my-crawl-template",
    "url": "https://docs.example.com",
    "variables": { "maxPages": 50 }
  }'

Search com template

curl -X POST "https://api.anycrawl.dev/v1/search" \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "template_id": "my-search-template",
    "query": "machine learning tutorials",
    "variables": { "lang": "en" }
  }'

Variáveis

Templates podem declarar variáveis para aceitar entradas dinâmicas na chamada.

• Cada variável tem um type: string, number, boolean ou url
• Podem ser required ou opcionais com defaultValue
• Veja a descrição do template para saber o que é esperado

Exemplo de requisição com variáveis:

{
    "template_id": "blog-scraper",
    "url": "https://example.com/blog/post-123",
    "variables": {
        "author": "john-doe",
        "includeComments": true,
        "maxComments": 50
    }
}

Se faltar variável obrigatória ou o tipo estiver errado, você recebe erro de validação 400.

Formato da resposta

As respostas com template seguem o mesmo formato das chamadas padrão:

{
    "success": true,
    "data": {
        "url": "https://example.com",
        "markdown": "# Page Title\n\nContent...",
        "metadata": { ... },
        // Campos adicionais de handlers personalizados (se houver)
        "extractedData": { ... }
    }
}

Templates com handlers personalizados podem acrescentar campos extras.

Tratamento de erros

Erros comuns ao usar templates:

Exemplo de resposta de erro:

{
    "success": false,
    "error": "Validation error",
    "message": "When using template_id, only template_id, url, variables are allowed. Invalid fields: engine, formats",
    "data": {
        "type": "validation_error",
        "issues": [
            {
                "field": "engine",
                "message": "Field 'engine' is not allowed when using template_id",
                "code": "invalid_field"
            }
        ],
        "status": "failed"
    }
}

Boas práticas

Para quem chama a API

• Sempre confira a descrição do template: variáveis obrigatórias e domínios/palavras-chave permitidos
• Use templates do marketplace quando possível para ganhar tempo
• Trate 404 (template removido ou arquivado)
• Não tente sobrescrever configurações do template (engine, formats etc.) — a chamada falhará

Para autores de templates

• Mantenha o template focado em um único caso de uso
• Documente todas as variáveis com descrições claras
• Use restrições de domínio para evitar uso indevido
• Defina preço adequado à complexidade
• Teste bem antes de publicar

Criar templates (avançado)

Ao criar seus próprios templates, você pode configurar:

Restrições de domínio

Limite onde o template pode ser usado:

{
    "allowedDomains": {
        "type": "glob",
        "patterns": ["*.example.com", "docs.mysite.com"]
    }
}

• type: "exact" (correspondência exata) ou "glob" (padrão)
• patterns: lista de domínios ou padrões permitidos

Restrições de palavra-chave (templates de busca)

Limite quais consultas podem ser usadas:

{
    "allowedKeywords": {
        "type": "glob",
        "patterns": ["*tutorial*", "*documentation*"]
    }
}

• allowedKeywords é validada antes da execução da consulta.
• type: "exact" ou "glob"
• patterns: valores/padrões permitidos
• A validação ocorre antes de queryTransform.

Preço

Defina o custo em créditos por chamada:

{
    "pricing": {
        "perCall": 10,
        "currency": "credits"
    }
}

Handlers personalizados

Código JavaScript/TypeScript para:

• requestHandler: pós-processar resultados do scrape e adicionar campos
• failedRequestHandler: tratar falhas com lógica de retry
• queryTransform (somente busca): transformar consultas antes da busca
• urlTransform (scrape/crawl): transformar URLs antes do processamento

Ambos os transforms suportam:

• Modo template com placeholders (query: {{query}}, url: {{url}})
• Modo append com prefix e suffix
• regexExtract opcional para extrair substring antes do modo

Exemplo de extração regex para perfis TikTok:

{
    "customHandlers": {
        "urlTransform": {
            "enabled": true,
            "mode": "append",
            "prefix": "",
            "suffix": "",
            "regexExtract": {
                "pattern": "^(https?:\\/\\/www\\.tiktok\\.com\\/@[^\\/?#]+)",
                "flags": "i",
                "group": 1
            }
        }
    }
}

Isso extrai https://www.tiktok.com/@piperrockelle de entradas como:

• https://www.tiktok.com/@piperrockelle?abb=ccc
• https://www.tiktok.com/@piperrockelle

Exemplo de requestHandler:

// Extract structured data from page context
const title = context.data.title;
const content = context.data.markdown;

return {
    extractedTitle: title,
    wordCount: content.split(/\s+/).length,
    customMetric: calculateMetric(content),
};

Modelo de segurança

• Templates não confiáveis: executam em sandbox VM endurecida com limitações rígidas
• Templates confiáveis: podem usar funções async com acesso controlado à página do navegador

Somente templates revisados e aprovados pelo AnyCrawl podem ser marcados como confiáveis.

FAQ

Posso sobrescrever engine ou formats do template?

Não. Templates são configurações imutáveis. Você só pode informar url/query e variables.

O que acontece se eu usar um template do marketplace?

Templates do marketplace são públicos. Você paga os créditos definidos pelo autor.

Os templates veem minha chave de API?

Não. Executam em sandboxes isolados sem acesso às suas credenciais.

Como crio meus próprios templates?

Use o playground AnyCrawl para criar e testar. Após publicar, ficam disponíveis via API.

Veja também

• Documentação da API Scrape
• Documentação da API Crawl
• Documentação da API Search
• Template Marketplace