API de scraping do TikTok: como obter dados de vídeos em JSON com jsonscraper

Se seu aplicativo precisa de informações sobre um vídeo específico do TikTok, é mais fácil começar com uma única solicitação e verificar quais dados ela retorna. Depois, você pode validar a resposta e prepará-la para armazenamento ou análise.

A página da API de scraping do TikTok da jsonscraper lista rotas para vídeos, usuários, pesquisas, hashtags, músicas e outros tipos de dados. A seguir, vamos analisar a solicitação documentada getVideoByID e formas seguras de processar a resposta. Os exemplos se baseiam nos materiais do fornecedor; antes de usá-los, teste-os com uma chave válida e a documentação atualizada.

Primeira solicitação: obter informações de um vídeo

A documentação de getVideoByID no Postman especifica o método GET e o parâmetro video_id. O exemplo também mostra region e cache_timeout. O endereço-base publicado na página do serviço é https://tiktok.evelode.com.

Exemplo de solicitação com cURL:

export JSONSCRAPER_LICENSE_KEY="sua_chave"

curl --get "https://tiktok.evelode.com/getVideoByID" \
  --data-urlencode "video_id=7106855913906081070" \
  --data-urlencode "license_key=$JSONSCRAPER_LICENSE_KEY" \
  --data-urlencode "region=US"

O ID do exemplo foi retirado de uma solicitação publicada. Substitua-o pelo ID do vídeo que deseja verificar. Armazene a chave em uma variável de ambiente ou em um gerenciador de segredos: não a adicione a um repositório público, ao JavaScript do cliente ou aos logs.

O Postman descreve region como um código de região e indica US como valor padrão. Para cache_timeout, a documentação indica um período de cache padrão de 3600 segundos; o valor 0 desativa o cache. Se esse parâmetro for necessário para seu caso de uso, você pode informá-lo explicitamente:

curl --get "https://tiktok.evelode.com/getVideoByID" \
  --data-urlencode "video_id=7106855913906081070" \
  --data-urlencode "license_key=$JSONSCRAPER_LICENSE_KEY" \
  --data-urlencode "region=US" \
  --data-urlencode "cache_timeout=0"

Esta é uma adaptação dos parâmetros publicados para a rota, não uma garantia de que todas as respostas terão a mesma estrutura ou de que desativar o cache seja adequado a qualquer tarefa. Antes da implementação, confira a autenticação e os parâmetros na coleção atual: o Postman pode enviar a chave por meio de uma API Key configurada, enquanto o exemplo de cURL acima a mostra como parâmetro de URL.

A mesma solicitação em Python

A seguir está uma versão que usa a biblioteca padrão do Python. Ela cria uma solicitação GET, envia os parâmetros e trata erros de rede, erros HTTP e JSON inválido.

import json
import os
from urllib.error import HTTPError, URLError
from urllib.parse import urlencode
from urllib.request import Request, urlopen

base_url = "https://tiktok.evelode.com/getVideoByID"
license_key = os.environ.get("JSONSCRAPER_LICENSE_KEY")

if not license_key:
    raise RuntimeError("Defina a variável JSONSCRAPER_LICENSE_KEY")

params = {
    "video_id": "7106855913906081070",
    "license_key": license_key,
    "region": "US",
}

url = f"{base_url}?{urlencode(params)}"
request = Request(url, method="GET")

try:
    with urlopen(request, timeout=30) as response:
        status_code = response.status
        payload = json.loads(response.read().decode("utf-8"))
except HTTPError as error:
    print(f"Erro HTTP: {error.code}")
    raise
except URLError as error:
    print(f"Erro de rede: {error.reason}")
    raise
except json.JSONDecodeError:
    raise RuntimeError("Não foi possível analisar a resposta do serviço como JSON")

print("Status HTTP:", status_code)
print("Chaves de nível superior:", list(payload.keys()))

Esta é uma adaptação da solicitação documentada, não um exemplo que o fornecedor tenha testado separadamente para Python. Ela também não abrange todas as respostas possíveis do serviço. Como a chave é enviada na URL, não imprima a URL completa nos logs: ela pode conter um segredo.

Como verificar a resposta JSON

A resposta publicada no Postman contém o campo status e um objeto aninhado tiktok.aweme_detail com dados do vídeo e do autor. Essa é a estrutura de um exemplo de resposta, não uma garantia de esquema invariável. Você pode consultá-la no exemplo de resposta de getVideoByID.

Ao ler campos aninhados, verifique cada nível:

def get_video_details(payload):
    tiktok = payload.get("tiktok")
    if not isinstance(tiktok, dict):
        return None

    details = tiktok.get("aweme_detail")
    if not isinstance(details, dict):
        return None

    return details

details = get_video_details(payload)

if details is None:
    print("A resposta não contém o objeto esperado com os dados do vídeo")
else:
    video_id = details.get("id")
    description = details.get("desc")
    author = details.get("author")

    print("ID:", video_id)
    print("Descrição:", description)
    print("Autor:", author)

Os nomes dos campos foram retirados do exemplo publicado. Usar .get() não significa que os campos sejam obrigatórios: isso permite processar uma resposta sem os valores esperados. Se a lógica do aplicativo depender de um campo específico, verifique se ele está presente nas respostas do seu caso de uso e defina o que fazer quando estiver ausente.

É útil separar três verificações:

1. Transporte: foi recebida uma resposta HTTP e qual é o status dela?
2. Formato: foi possível analisar o corpo da resposta como JSON?
3. Conteúdo: os dados necessários para o aplicativo estão presentes?

Conseguir analisar o JSON não significa que a resposta contenha o objeto necessário. Para fins de diagnóstico, registre os erros técnicos e os resultados das verificações, ocultando as chaves.

De uma solicitação a um fluxo de trabalho

Para um protótipo, basta enviar a solicitação e exibir alguns valores. Para processamento recorrente, divida o trabalho em etapas:

Solicitação → verificação → normalização → deduplicação → armazenamento.

• Solicitação. Obtenha a resposta pela rota documentada e salve o status técnico separadamente.
• Verificação. Confirme que o corpo pode ser analisado como JSON e contém os dados necessários para a tarefa específica.
• Normalização. Transfira os valores necessários para seu próprio modelo de dados. Não copie toda a estrutura aninhada para o banco de dados se o aplicativo precisar apenas de alguns campos.
• Deduplicação. Escolha um identificador depois de confirmar que ele está presente e é adequado à sua tarefa. Não presuma que ele estará sempre disponível em todas as respostas.
• Armazenamento. Se necessário, salve o horário da solicitação e a resposta original separadamente do registro normalizado. Isso ajudará a entender quais alterações foram feitas pelo aplicativo.

Estas são recomendações sobre a arquitetura do aplicativo, não funcionalidades que devam ser atribuídas ao serviço. Separar a resposta externa do modelo interno também facilita lidar com mudanças: os problemas podem ser identificados na etapa de verificação ou normalização, em vez de espalhados pelo código.

Para solicitações recorrentes, defina antecipadamente quando atualizar os dados e quais erros devem ser repetidos. Limite o número de tentativas: um ciclo infinito não corrigirá um parâmetro inválido nem um problema de autenticação.

Cache e região

Na descrição da rota getVideoByID, o parâmetro cache_timeout define o tempo de cache em segundos: o valor padrão indicado é 3600 segundos, e 0 desativa o cache. O parâmetro region é descrito como um código de país; a documentação apresenta US como exemplo. Antes da implementação, confira essas informações na documentação atual da solicitação no Postman.

A existência de uma configuração de cache não confirma que uma resposta específica seja atualizada. Se a atualidade dos dados for importante, verifique os resultados de solicitações repetidas com dados do seu caso de uso e escolha o comportamento adequado.

Quais tarefas explorar em seguida

A página do produto lista rotas para pesquisas de vídeos e usuários, hashtags, localizações, músicas e tendências. Entre os exemplos estão searchVideo, searchHashtag, getUserFeed e getTrendingFeed. Esse é um mapa de rotas publicado pelo fornecedor, não uma verificação independente de cada uma delas. Consulte os parâmetros e o formato da resposta na documentação de cada rota: não é possível transferi-los automaticamente do exemplo de getVideoByID.

A jsonscraper recomenda usar a coleção do Postman para configurar a chave e executar solicitações. Essa pode ser uma forma conveniente de testar uma rota específica antes de escrever uma integração. O serviço também lista cenários de automação, mas a compatibilidade de cada fluxo deve ser verificada separadamente na sua configuração. Ao exportar ou compartilhar a coleção, confirme que ela não contém uma chave ativa.

O que verificar antes de usar no aplicativo

Antes de incluir a solicitação em um processo recorrente, teste-a com os vídeos e parâmetros necessários para o projeto:

• A solicitação é executada com uma chave válida e um ID correto?
• Como o aplicativo lida com um parâmetro inválido ou ausente?
• O que acontece se o JSON for válido, mas o campo necessário não estiver presente?
• Como são tratados erros HTTP, falhas de rede e tempos limite?
• Quais campos são adequados para identificação e deduplicação especificamente na sua tarefa?
• Como o resultado de uma solicitação repetida muda com diferentes valores de cache_timeout, se você usar esse parâmetro?

Registre a data do teste, os parâmetros sem segredos e um exemplo de resposta anonimizado. Uma solicitação bem-sucedida confirma apenas o funcionamento de um cenário específico em determinadas condições; não comprova a estabilidade de todas as rotas e respostas.

Comece com um cenário reproduzível

Teste getVideoByID com o vídeo desejado, analise o JSON efetivamente recebido e escreva um manipulador que leve em conta campos ausentes e erros. Depois, se necessário, amplie o processo com normalização, deduplicação e armazenamento.

A documentação da jsonscraper oferece um ponto de partida: o endereço-base e o mapa de rotas. Ainda assim, o código de produção precisa verificar cada resposta, proteger a chave e prever situações em que os dados sejam diferentes da estrutura esperada.