Skip to main content

​
Introdução

Os endpoints de Search Posts no mundo v2 permitem receber Posts relacionados a tópicos de interesse, com base em uma consulta de busca que você elabora. Temos dois endpoints diferentes disponíveis com o v2 Search Posts: recent search, que está disponível para todos os desenvolvedores com uma conta aprovada e pode buscar Posts de até sete dias de idade, e full-archive search, que está disponível apenas para pesquisadores aprovados para a trilha de produto Academic Research, e pode pesquisar em todo o arquivo de Posts desde março de 2006. Você pode ver toda a nossa oferta de busca em nossa página de visão geral de busca. Esses endpoints de Search Posts atendem a um dos casos de uso mais comuns para pesquisadores acadêmicos, que podem usá-los para estudos longitudinais ou análise de um tópico ou evento passado. Este tutorial fornece um guia passo a passo para pesquisadores que desejam usar o endpoint full-archive search para pesquisar todo o histórico de dados públicos do X. Também demonstrará as diferentes maneiras de construir um conjunto de dados, como obter Posts com geotag, e como paginar pelos Posts disponíveis para uma consulta.

​
Pré-requisitos

Atualmente, este endpoint está disponível apenas como parte da trilha de produto Academic Research. Para usar este endpoint, você deve solicitar acesso. Saiba mais sobre a inscrição e os requisitos para esta trilha.

​
Conecte um app ao projeto acadêmico

Depois de ser aprovado para usar a trilha de produto Academic Research, você verá seu Project acadêmico no Developer Console. Na seção “Apps”, clique em “Add App” para conectar seu X App ao Project. Esta imagem exibe um Project acadêmico no Developer Console que ainda não tem um App adicionado Em seguida, você pode escolher um App existente e conectá-lo ao seu projeto (como mostrado abaixo). Esta imagem mostra a página que aparece quando você tenta adicionar um App ao seu Project Acadêmico Ou você pode criar um novo App, dar a ele um nome e clicar em concluir, para conectar um novo App ao seu Project Acadêmico. Esta imagem mostra a página onde você inserirá um nome para seu novo App, ou permite selecionar um App existente Isso lhe dará suas chaves de API e Bearer Token que você poderá usar para se conectar ao endpoint full-archive search. Esta imagem mostra a página exibida após criar um novo App que mostra suas chaves e tokens Observação As chaves na captura de tela acima estão ocultas, mas no seu próprio Developer Console, você poderá ver os valores reais da API Key, API Secret Key e Bearer Token. Salve essas chaves e o Bearer Token porque você precisará deles para chamar o endpoint full-archive search. O comando cURL abaixo mostra como você pode obter Posts históricos do handle @XDevelopers. Substitua $BEARER_TOKEN pelo seu próprio Bearer Token, cole a requisição completa no seu terminal e pressione “return”.
Você verá o JSON de resposta. Por padrão, apenas os 10 Posts mais recentes serão retornados. Se você quiser mais de 10 Posts por requisição, pode usar o parâmetro max_results e defini-lo para um máximo de 500 Posts por requisição, como mostrado abaixo:

​
Construindo queries

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 obter todos os Posts que contêm a palavra covid ou a palavra coronavirus, você pode usar o operador OR entre parênteses, e sua consulta pode ser (covid OR coronavirus), e assim sua chamada de API ficará assim:
Da mesma forma, se você quiser todos os Posts que contêm a palavra covid19 que não são reposts, pode usar o operador is:retweet com o NOT lógico (representado por -), então sua consulta pode ser covid19 -is:retweet e sua chamada de API será:
Confira este guia para uma lista completa de operadores suportados no endpoint full-archive search.

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

Ao usar o endpoint full-archive search, por padrão os Posts dos últimos 30 dias serão retornados. Se você quiser obter Posts com mais de 30 dias, pode usar os parâmetros start_time e end_time em 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á:

​
Obtendo Posts históricos com geotag

Posts com geotag são Posts que possuem informações geográficas associadas a eles, como cidade, estado, país etc.

​
Usando o operador has:geo

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

​
Usando o operador place_country

Da mesma forma, você pode limitar os Posts que têm dados de geolocalização a um país específico, usando o operador place_country. O comando cURL abaixo obterá todos os Posts do handle @XDevelopers dos Estados Unidos:
O país é especificado acima usando o código de dois caracteres ISO alpha-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ê só pode obter até 500 Posts por requisição para uma consulta ao endpoint full-archive search. Se houver mais de 500 Posts disponíveis para sua consulta, sua resposta json incluirá um next_token que você pode adicionar à sua chamada de API para obter os próximos Posts disponíveis para essa consulta. Este next_token está disponível no objeto meta da sua resposta JSON, que se parece com algo assim:
Assim, para obter os próximos Posts disponíveis, use o valor de next_token deste objeto meta e use o valor como valor do next_token em sua chamada de API para o endpoint full-archive search, como mostrado abaixo (Você usará seu próprio Bearer Token e o valor que você obtém para o Next Token da sua chamada de API anterior).
Dessa forma, você pode continuar verificando se há um next_token disponível e, se você não tiver atingido o número desejado de Posts a serem coletados, pode continuar chamando o endpoint full-archive com o novo next_token para cada requisição. Abaixo estão alguns recursos que podem ajudar você ao usar o endpoint full-archive search. Adoraríamos ouvir seu feedback. Entre em contato conosco em @XDevelopers ou em nossos fóruns da comunidade com perguntas sobre este endpoint.

​
Recursos adicionais