Obtendo Posts históricos com o endpoint de pesquisa de arquivo completo da v2

​

Introdução

Os endpoints de Search Posts no contexto da v2 permitem receber Posts relacionados a tópicos de interesse, com base em uma query de pesquisa que você cria. Temos dois endpoints diferentes disponíveis com o v2 Search Posts: pesquisa recente, disponível para todos os desenvolvedores com uma conta aprovada e que permite buscar Posts de até sete dias, e pesquisa de arquivo completo, disponível apenas para pesquisadores aprovados para o Academic Research product track, que permite pesquisar em todo o arquivo de Posts desde março de 2006.

Você pode ver nossa oferta completa de pesquisa na página de visão geral de pesquisa.

Esses endpoints de Search Posts atendem a um dos casos de uso mais comuns para pesquisadores acadêmicos, que podem utilizá-los para estudos longitudinais ou para analisar um tópico ou evento passado.

Este tutorial fornece um guia passo a passo para pesquisadores que desejam usar o endpoint de pesquisa de arquivo completo para consultar todo o histórico público de X data. Ele também demonstrará diferentes maneiras de construir um dataset, como recuperar Posts com geotag, e como paginar pelos Posts disponíveis para uma query.

​

Pré-requisitos

Atualmente, este endpoint está disponível apenas como parte do rastro de produto Academic Research. Para usar este endpoint, você deve solicitar acesso. Saiba mais sobre a candidatura e os requisitos deste rastro.

​

Conectar um App ao Projeto acadêmico

Assim que você for aprovado para usar o produto Academic Research, verá seu Projeto acadêmico no portal do desenvolvedor. Na seção “Projects and Apps”, clique em “Add App” para conectar seu X App ao Projeto.

Em seguida, você pode escolher um App existente e conectá-lo ao seu Projeto (como mostrado abaixo).

Ou você pode criar um novo App, atribuir um nome a ele e clicar em Concluir para conectar um novo App ao seu Projeto acadêmico.

Isso exibirá suas chaves de API e o Bearer Token, que você poderá usar para se conectar ao endpoint de pesquisa no arquivo completo.

Atenção

As chaves na captura de tela acima estão ocultas, mas no seu próprio portal do desenvolvedor você poderá ver os valores reais da API Key, da Chave secreta da API e do Bearer Token. Salve essas chaves e o Bearer Token, pois você precisará deles para chamar o endpoint de pesquisa no arquivo completo.

​

Conectando-se ao endpoint de pesquisa de arquivo completo

O comando cURL abaixo mostra como obter Posts históricos do @XDevelopers. Substitua $BEARER_TOKEN pelo seu próprio Bearer Token, cole a solicitação completa no terminal e pressione Enter.

curl --request GET 'https://api.x.com/2/tweets/search/all?query=from:xdevelopers' --header 'Authorization: Bearer $BEARER_TOKEN'

Você verá o JSON de resposta.

Por padrão, apenas os 10 Posts mais recentes serão retornados. Se quiser mais de 10 Posts por solicitação, use o parâmetro max_results e defina-o como no máximo 500 Posts por solicitação, como mostrado abaixo:

curl --request GET 'https://api.x.com/2/tweets/search/all?query=from:xdevelopers&max_results=500' --header 'Authorization: Bearer $BEARER_TOKEN'

​

Criando consultas

Como você pode ver nos exemplos de chamadas acima, usando o parâmetro query, é possível especificar os dados que deseja pesquisar. Por exemplo, se quiser recuperar todos os Posts que contêm a palavra covid ou a palavra coronavirus, você pode usar o operador OR entre parênteses, e sua query pode ser (covid OR coronavirus) e, assim, sua chamada à API ficará da seguinte forma:

curl --request GET 'https://api.x.com/2/tweets/search/all?query=(covid%20OR%20coronavirus)&max_results=500' --header 'Authorization: Bearer $BEARER_TOKEN'

Da mesma forma, se você quiser todos os Posts que contêm a palavra covid19 e que não são Retweets, você pode usar o operador is:retweet com o NOT lógico (representado por -); assim, sua query pode ser covid19 -is:retweet e sua chamada à API será:

curl --request GET 'https://api.x.com/2/tweets/search/all?query=covid19%20-is:retweet&max_results=500' --header 'Authorization: Bearer $BEARER_TOKEN'

Confira este guia com a lista completa de operadores compatíveis no endpoint de pesquisa de arquivo completo.

​

Usando os parâmetros start_time e end_time para obter Posts históricos

Ao usar o endpoint de pesquisa no arquivo completo, por padrão serão retornados Posts dos últimos 30 dias. Se você quiser obter Posts com mais de 30 dias, pode usar os parâmetros start_time e end_time na sua chamada de API. Esses parâmetros devem estar em um formato de data e hora RFC3339 válido, por exemplo, 2020-12-21T13:00:00.00Z. Assim, se você quiser obter todos os Posts da conta XDevelopers no mês de dezembro de 2020, sua chamada de API será:

curl --request GET 'https://api.x.com/2/tweets/search/all?query=from:XDevelopers&start_time=2020-12-01T00:00:00.00Z&end_time=2021-01-01T00:00:00.00Z' --header 'Authorization: Bearer $BEARER_TOKEN'

​

Obtendo Posts históricos com geotag

Posts com geotag são Posts que têm informações geográficas associadas, como cidade, estado, país etc.

​

Usando o operador has:geo

Se você quiser obter Posts que contêm dados de geolocalização, pode usar o operador has:geo. Por exemplo, a seguinte solicitação cURL retornará apenas os Posts do perfil @XDevelopers que têm dados de geolocalização:

curl --request GET
'https://api.x.com/2/tweets/search/all?query=from:xdevelopers%20has:geo' --header
'Authorization: Bearer $BEARER_TOKEN'

​

Usando o operador place_country

Da mesma forma, você pode limitar os Posts que têm dados geográficos a um país específico usando o operador place_country. O comando cURL abaixo recuperará todos os Posts da conta @XDevelopers dos Estados Unidos:

curl --request GET
'https://api.x.com/2/tweets/search/all?query=from:xdevelopers%20place_country:US'
--header 'Authorization: Bearer XXXXX'

O país é indicado acima usando o código ISO alfa-2. Códigos ISO válidos podem ser encontrados aqui.

​

Obtendo mais de 500 Posts históricos usando o next_token

Como mencionado acima, por padrão você pode obter no máximo 500 Posts por solicitação ao fazer uma query no endpoint de pesquisa de arquivo completo. Se houver mais de 500 Posts disponíveis para sua query, a resposta JSON incluirá um next_token que você pode anexar à sua chamada de API para obter os próximos Posts disponíveis para essa query. Esse next_token está disponível no objeto meta da sua resposta JSON, que é algo como:

{ "newest_id": "12345678...", "oldest_id": "12345678...", "result_count": 500,
"nebashxt_token": "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" }

Assim, para obter os próximos Posts disponíveis, use o valor de next_token desse objeto meta e passe esse valor como next_token na sua chamada de API para o endpoint de busca no arquivo completo, conforme mostrado abaixo (você usará seu próprio Bearer Token e o Next Token recebido na chamada de API anterior).

curl --request GET
'https://api.x.com/2/tweets/search/all?max_results=500&query=covid&next_token=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX'
--header 'Authorization: Bearer $BEARER_TOKEN'

Dessa forma, você pode continuar verificando se há um next_token disponível e, se ainda não tiver atingido o número desejado de Posts a serem coletados, pode continuar chamando o endpoint de arquivo completo com o novo next_token para cada solicitação. Lembre-se de que o endpoint de pesquisa no arquivo completo conta para o seu total de Post cap, ou seja, o número de Posts por mês que você pode obter da X API por Projeto. Portanto, fique atento à lógica do seu código ao paginar os resultados para garantir que você não acabe, inadvertidamente, esgotando seu Post cap.

Abaixo estão alguns recursos que podem ajudar ao usar o endpoint de pesquisa no arquivo completo. Adoraríamos receber seu feedback. Entre em contato conosco em @XDevelopers ou em nossos fóruns da comunidade com perguntas sobre este endpoint.

​

Recursos adicionais

• Referência da API do endpoint de busca em arquivo completo
• Aprenda o básico de como criar uma query de busca