Casos de Uso para a API de Tráfego do Site

Seus stakeholders querem um painel que mostre de onde vem o tráfego, quais países importam e quão engajados os visitantes estão. Ao final deste artigo, você terá uma integração que busca a cobertura de países e fontes de tráfego em nível de domínio, principais países e métricas de engajamento usando a API de Tráfego do Site no Zyla API Hub.

O que esta API entrega

A API de Tráfego do Site fornece inteligência de tráfego em nível de domínio que você pode inserir em análises de produtos, ferramentas de SEO ou fluxos de trabalho de pesquisa competitiva. Você passa um domínio e recebe:

• Os 5 principais países por participação de tráfego (com identificadores numéricos de países e códigos ISO alpha-2).
• Métricas de engajamento, incluindo taxa de rejeição, páginas por visita, visitas e tempo no site.
• Metadados de site de alto nível (título, descrição).

Também expõe um diretório de países com códigos ISO e regiões para que você possa rotular ou filtrar o tráfego específico de países com precisão em sua interface ou relatórios.

Começando no Zyla API Hub

Abra a listagem da API de Tráfego do Site no Zyla API Hub e inscreva-se. A Zyla fornece uma conta, uma chave de API e um modelo de assinatura + cota em mais de 10.000 APIs públicas. Para esta API, você pode começar com um teste de 7 dias ou 50 solicitações; verifique a listagem para opções de acesso e preços atuais.

Uma vez inscrito, você receberá uma chave de API. Todas as solicitações abaixo usam:

• Cabeçalho: Authorization: Bearer YOUR_API_KEY
• Método HTTP: GET

Navegue por outras categorias ou gerencie suas assinaturas a qualquer momento no Zyla API Hub. Quando estiver pronto para implementar, comece o teste aqui: Iniciar teste de 7 dias na API de Tráfego do Site.

Endpoints que você usará

1) Lista de Países

Receba a lista de todos os países suportados e seus códigos. Esses códigos são referenciados nas respostas de análise de tráfego para que você possa renderizar nomes de países e regiões corretamente.

Método: GET

URL: https://zylalabs.com/api/29/site-traffic-api/1372/countries-list

cURL

curl -s -X GET "https://zylalabs.com/api/29/site-traffic-api/1372/countries-list" \
-H "Authorization: Bearer YOUR_API_KEY"

Resposta de exemplo oficial

[{"name":"Afghanistan","alpha-2":"AF","alpha-3":"AFG","country-code":"004","iso_3166-2":"ISO 3166-2:AF","region":"Asia","sub-region":"Southern Asia","intermediate-region":"","region-code":"142","sub-region-code":"034","intermediate-region-code":""},{"name":"Åland Islands","alpha-2":"AX","alpha-3":"ALA","country-code":"248","iso_3166-2":"ISO 3166-2:AX","region":"Europe","sub-region":"Northern Europe","intermediate-region":"","region-code":"150","sub-region-code":"154","intermediate-region-code":""},{"name":"Albania","alpha-2":"AL","alpha-3":"ALB","country-code":"008","iso_3166-2":"ISO 3166-2:AL","region":"Europe","sub-region":"Southern Europe","intermediate-region":"","region-code":"150","sub-region-code":"039","intermediate-region-code":""},{"name":"Algeria","alpha-2":"DZ","alpha-3":"DZA","country-code":"012","iso_3166-2":"ISO 3166-2:DZ","region":"Africa","sub-region":"Northern Africa","intermediate-region":"","region-code":"002","sub-region-code":"015","intermediate-region-code":""},{"name":"American Samoa","alpha-2":"AS","alpha-3":"ASM","country-code":"016","iso_3166-2":"ISO 3166-2:AS","region":"Oceania","sub-region":"Polynesia","intermediate-region":"","region-code":"009","sub-region-code":"061","intermediate-region-code":""},{"name":"Andorra","alpha-2":"AD","alpha-3":"AND","country-code":"020","iso_3166-2":"ISO 3166-2:AD","region":"Europe","sub-region":"Southern Europe","intermediate-region":"","region-code":"150","sub-region-code":"039","intermediate-region-code":""},{"name":"Angola","alpha-2":"AO","alpha-3":"AGO","country-code":"024","iso_3166-2":"ISO 3166-2:AO","region":"Africa","sub-region":"Sub-Saharan Africa","intermediate-region":"Middle Africa","region-code":"002","sub-region-code":"202","intermediate-region-code":"017"},{"name":"Anguilla","alpha-2":"AI","alpha-3":"AIA","country-code":"660","iso_3166-2":"ISO 3166-2:AI","region":"Americas","sub-region":"Latin America and the Caribbean","intermediate-region":"Caribbean","region-code":"019","sub-region-code":"419","intermediate-region-code":"029"},{"name":"Antarctica","alpha-2":"AQ","alpha-3":"ATA","country-code":"010","iso_3166-2":"ISO 3166-2:AQ","region":"","sub-region":"","intermediate-region":"","region-code":"","sub-region-code":"","intermediate-region-code":""},{"name":"Antigua e Barbuda","alpha-2":"AG","alpha-3":"ATG","country-code":"028","iso_3166-2":"ISO 3166-2:AG","region":"Américas","sub-region":"América Latina e Caribe","intermediate-region":"Caribe","region-code":"019","s…

Como usá-lo:

• Mapeie os códigos ISO de duas letras das respostas de tráfego para nomes legíveis usando o campo “alpha-2”.
• Agrupe ou filtre por “região” e “sub-região” ao construir rollups.
• Armazene este conjunto de dados localmente e atualize periodicamente para evitar consultas repetidas.

2) Fonte de Tráfego e Visão Geral

Forneça um domínio (sem protocolo ou “www”) para recuperar os 5 principais países por participação de tráfego e métricas de engajamento, além de metadados de site de alto nível.

Método: GET

URL: https://zylalabs.com/api/29/site-traffic-api/93/traffic-source-and-overview

Parâmetro de consulta necessário:

• domain: o domínio que você deseja analisar (exemplo: google.com)

cURL

A resposta inclui campos como:

• SiteName, Title, Description
• TopCountryShares: array de objetos com Country, CountryCode, Value
• Engagments: BounceRate, PagePerVisit, Visits, TimeOnSite, Month, Year
• EstimatedMonthlyVisits: um objeto indexado por datas (ex: “YYYY-MM-01”) mapeando para contagens de visitas

Nota: O endpoint de Fonte de Tráfego e Visão Geral requer apenas o parâmetro de domínio; não inclua protocolos ou subdomínios como “www”.

Código que você pode colar

Exemplo em Python: buscar visão geral do tráfego e resumir campos principais

Este trecho chama o endpoint de Fonte de Tráfego e Visão Geral para um único domínio e imprime as participações de países e métricas de engajamento. Substitua YOUR_API_KEY pela sua chave do Zyla.

import requests
from typing import Dict, Any

API_KEY = "YOUR_API_KEY"
DOMAIN = "google.com"

url = "https://zylalabs.com/api/29/site-traffic-api/93/traffic-source-and-overview"
params = {"domain": DOMAIN}
headers = {"Authorization": f"Bearer {API_KEY}"}

resp = requests.get(url, headers=headers, params=params, timeout=30)
resp.raise_for_status()
data: Dict[str, Any] = resp.json()

print("Site:", data.get("SiteName"))
print("Title:", data.get("Title"))
print("Description:", data.get("Description"))

eng = data.get("Engagments", {}) or {}
print("Engajamento:")
print(" BounceRate:", eng.get("BounceRate"))
print(" PagePerVisit:", eng.get("PagePerVisit"))
print(" Visits:", eng.get("Visits"))
print(" TimeOnSite (segundos):", eng.get("TimeOnSite"))
print(" Período:", f'{eng.get("Year")}-{eng.get("Month")}')

top_countries = data.get("TopCountryShares", []) or []
print("\nParticipações dos Principais Países:")
for item in top_countries:
code = item.get("CountryCode")
share = item.get("Value")
print(f" {code}: {share}")

monthly = data.get("EstimatedMonthlyVisits", {}) or {}
# Pegue a chave do último mês se disponível, ordenada por chave (formato YYYY-MM-01)
if monthly:
latest_key = sorted(monthly.keys())[-1]
print("\nÚltimas Visitas Mensais Estimadas:")
print(f" {latest_key}: {monthly[latest_key]}")

Dica: A resposta contém valores numéricos e alguns números codificados como strings (ex: taxa de rejeição, visitas em Engagments). Se você precisar de matemática numérica, converta as strings para float ou int antes das agregações.

Casos de uso práticos que você pode entregar esta semana

• Quebra de tráfego ciente do país dentro de um painel de marketing: Chame Fonte de Tráfego e Visão Geral, renderize TopCountryShares com nomes de países da Lista de Países.
• Widget de monitoramento competitivo: Para uma lista curta de domínios concorrentes, consulte o endpoint em uma programação e plote EstimatedMonthlyVisits ao longo do tempo.
• Análise de oportunidades de SEO: Combine SiteName/Title/Description com PagePerVisit e BounceRate para priorizar domínios que valem a pena contatar ou parcerias.
• Planejamento de território: Use a Lista de Países para marcar países com regiões e somar a participação de tráfego por região, ajudando as equipes de vendas a focar seus esforços.
• Verificações de saúde de engajamento: Acompanhe TimeOnSite, PagePerVisit e BounceRate a cada mês para alertar quando o engajamento desvia além de um limite.

Detalhes de solicitação/resposta que economizam tempo

• Autenticação: Use Authorization: Bearer YOUR_API_KEY em cada solicitação.
• Formato de domínio: Forneça apenas o domínio (ex: “example.com”). Não inclua protocolo ou “www”.
• Campos de período de tempo: Engagments inclui Month e Year; as chaves de EstimatedMonthlyVisits parecem com “YYYY-MM-01”. Armazene como strings ou analise para datas.
• Códigos de país: As respostas de tráfego incluem Country (código numérico) e CountryCode (ISO alpha-2). Use a Lista de Países para mapear para nomes de países e regiões.
• Cache: Ambos os endpoints são GET; implemente cache do lado do cliente para reduzir chamadas redundantes em painéis ou páginas renderizadas pelo servidor.
• Paginação: Não aplicável nesses endpoints; as respostas são cargas completas para o domínio ou conjunto de dados solicitado.
• Modelo de acesso: Assinatura + cota. O uso pela primeira vez geralmente começa com um teste de 7 dias ou 50 solicitações—veja a listagem para detalhes atuais.

Chamando a API de agentes de IA via MCP

Se você executar seu fluxo de trabalho em um cliente compatível com MCP, pode direcionar chamadas através do endpoint MCP da Zyla. Configure seu agente para acessar:

Endpoint: https://mcp.zylalabs.com/mcp?apikey=YOUR_API_KEY

Isso permite que seu agente de IA invoque os mesmos endpoints da API de Tráfego do Site documentados acima, enquanto centraliza a autenticação através da sua chave Zyla. Para mais informações sobre MCP, veja a página MCP. Você ainda controla quais caminhos da API sua ferramenta chama e como os resultados são renderizados nas saídas do seu agente.

Exemplo de fluxo de trabalho de ponta a ponta

1. Busque a Lista de Países uma vez e armazene em cache por ETag ou timestamp em seu aplicativo, indexado por alpha-2.
2. Para cada domínio fornecido pelo usuário, chame Fonte de Tráfego e Visão Geral com domain=example.com.
3. Junte TopCountryShares.CountryCode ao seu mapa de países em cache para rótulos e regiões.
4. Renderize métricas de engajamento (BounceRate, PagePerVisit, Visits, TimeOnSite) ao lado das participações de países.
5. Se você chartar tendências, indexe EstimatedMonthlyVisits pela data analisada para garantir a ordenação correta.

Dicas de validação e QA

• Normalização de domínio: Converta para minúsculas e remova prefixos antes de chamar a API para evitar duplicatas.
• Manipulação de números: Converta numéricos de string em Engagments para tipos numéricos para aritmética, mas mantenha strings brutas para exibição se precisar de formatação exata.
• Rollups regionais: Use a Lista de Países “região” e “sub-região” para agregar tráfego; mantenha uma alternativa para campos de região vazios (ex: Antártica).
• Resiliência: Envolva chamadas com timeouts e tentativas; trate o conjunto de dados como eventualmente consistente e armazene em cache resultados recentes.

Por que Zyla para entrega rápida

Com uma conta e uma chave de API em todo o catálogo, você pode adicionar análises adjacentes ou enriquecimento mais tarde sem mudar seu modelo de autenticação. A cobrança é por assinatura + cota, o que simplifica o rastreamento de custos. Explore o catálogo no Zyla API Hub, depois inscreva-se na API de Tráfego do Site para obter as informações de tráfego exatas que você precisa esta semana.

FAQ

Qual formato de parâmetro o campo de domínio espera?
Use o domínio puro sem protocolo ou “www”, por exemplo: domain=example.com.

Como mapeio códigos de países em TopCountryShares para nomes legíveis?
Chame o endpoint da Lista de Países e junte-se ao código alpha-2 (CountryCode em TopCountryShares) para exibir o nome do país e a região.

Existem endpoints de paginação ou em lote?
Os endpoints documentados são GETs de chamada única sem paginação. Para processamento em lote, percorra sua lista de domínios e armazene resultados em cache.

Quais unidades de tempo são usadas nos dados de engajamento?
Engagments.TimeOnSite é expresso em segundos. BounceRate, PagePerVisit e Visits podem estar codificados como strings—converta para tipos numéricos se precisar de cálculos. Month e Year indicam o período da captura de engajamento.

Como inicio um teste e obtenho uma chave de API?
Inscreva-se na página de listagem para iniciar um teste de 7 dias ou 50 solicitações (verifique a página para acesso atual). Sua chave aparece no console da Zyla e é usada como Bearer YOUR_API_KEY nos cabeçalhos.

Pronto para construir? Inscreva-se e comece a obter inteligência de tráfego agora: Iniciar teste de 7 dias na API de Tráfego do Site.

Resposta oficial da API

[{"name":"Afeganistão","alpha-2":"AF","alpha-3":"AFG","country-code":"004","iso_3166-2":"ISO 3166-2:AF","region":"Ásia","sub-region":"Ásia Meridional","intermediate-region":"","region-code":"142","sub-region-code":"034","intermediate-region-code":""},{"name":"Ilhas Åland","alpha-2":"AX","alpha-3":"ALA","country-code":"248","iso_3166-2":"ISO 3166-2:AX","region":"Europa","sub-region":"Europa Setentrional","intermediate-region":"","region-code":"150","sub-region-code":"154","intermediate-region-code":""},{"name":"Albânia","alpha-2":"AL","alpha-3":"ALB","country-code":"008","iso_3166-2":"ISO 3166-2:AL","region":"Europa","sub-region":"Europa Meridional","intermediate-region":"","region-code":"150","sub-region-code":"039","intermediate-region-code":""},{"name":"Argélia","alpha-2":"DZ","alpha-3":"DZA","country-code":"012","iso_3166-2":"ISO 3166-2:DZ","region":"África","sub-region":"África Setentrional","intermediate-region":"","region-code":"002","sub-region-code":"015","intermediate-region-code":""},{"name":"Samoa Americana","alpha-2":"AS","alpha-3":"ASM","country-code":"016","iso_3166-2":"ISO 3166-2:AS","region":"Oceania","sub-region":"Polinésia","intermediate-region":"","region-code":"009","sub-region-code":"061","intermediate-region-code":""},{"name":"Andorra","alpha-2":"AD","alpha-3":"AND","country-code":"020","iso_3166-2":"ISO 3166-2:AD","region":"Europa","sub-region":"Europa Meridional","intermediate-region":"","region-code":"150","sub-region-code":"039","intermediate-region-code":""},{"name":"Angola","alpha-2":"AO","alpha-3":"AGO","country-code":"024","iso_3166-2":"ISO 3166-2:AO","region":"África","sub-region":"África Subsaariana","intermediate-region":"África Central","region-code":"002","sub-region-code":"202","intermediate-region-code":"017"},{"name":"Anguilla","alpha-2":"AI","alpha-3":"AIA","country-code":"660","iso_3166-2":"ISO 3166-2:AI","region":"Américas","sub-region":"América Latina e Caribe","intermediate-region":"Caribe","region-code":"019","sub-region-code":"419","intermediate-region-code":"029"},{"name":"Antártica","alpha-2":"AQ","alpha-3":"ATA","country-code":"010","iso_3166-2":"ISO 3166-2:AQ","region":"","sub-region":"","intermediate-region":"","region-code":"","sub-region-code":"","intermediate-region-code":""},{"name":"Antigua e Barbuda","alpha-2":"AG","alpha-3":"ATG","country-code":"028","iso_3166-2":"ISO 3166-2:AG","region":"Américas","sub-region":"América Latina e Caribe","intermediate-region":"Caribe","region-code":"019","s…