annotations de Post

​

Visão geral

As annotations foram adicionadas ao Objeto Post em todos os endpoints v2 que retornam um Objeto Post. As annotations de Post oferecem uma forma de compreender informações contextuais sobre o próprio Post. Embora 100% dos Posts sejam revisados, devido ao conteúdo do texto do Post, apenas uma parte recebe annotations.

1. Entity annotations (NER): As entidades incluem pessoas, lugares, produtos e organizações e são fornecidas na seção de payload entity. Elas são atribuídas programaticamente com base no que é mencionado explicitamente (reconhecimento de entidades nomeadas) no texto do Post.

2. Context annotations: Derivadas da análise do texto de um Post, as context annotations incluem um pareamento de domínio e entidade para ajudar a descobrir Posts sobre tópicos que anteriormente podiam ser difíceis de identificar. Atualmente usamos mais de 80 domínios para categorizar Posts. Um arquivo CSV com as entidades de context annotations disponíveis está em nosso repositório no GitHub.

​

Tipos de Anotação de Post

​

Entidades

As anotações de entidade são entidades definidas programaticamente no campo entities e aparecem como annotations no payload. Cada anotação tem uma pontuação de confiança e indica onde, no texto do Post, as entidades foram identificadas (usando os campos start e end).

Os tipos de anotação de entidade incluem:

• Pessoa - Exemplos: Barack Obama, Daniel, George W. Bush
• Lugar - Exemplos: Detroit, Cali, San Francisco
• Produto - Exemplos: Mountain Dew, Mozilla Firefox
• Organização - Exemplos: Chicago White Sox, IBM
• Outro - Exemplos: Diabetes, Super Bowl 50

​

Contexto

Última atualização: junho de 2022

As annotations de contexto são fornecidas no campo context_annotations do payload. Elas são inferidas com base na análise semântica de palavras‑chave, hashtags, handles etc. no texto do Post e resultam em rótulos de domínio e/ou de entidade. Atualmente, usamos mais de 80 domínios, conforme mostrado na tabela abaixo.

Categorias de Domínio	Códigos de Domínio
3: Programas de TV	46: Categoria de Marca
4: Episódios de TV	47: Marca
6: Eventos esportivos	48: Produto
10: Pessoa	54: Músico
11: Esporte	55: Gênero musical
12: Time esportivo	56: Ator
13: Lugar	58: Personalidade do entretenimento
22: Gêneros de TV	60: Atleta
23: Canais de TV	65: Vertical de interesses e hobbies
26: Liga esportiva	66: Categoria de interesses e hobbies
27: Jogo de futebol americano	67: Interesses e hobbies
28: Jogo de futebol da NFL	68: Jogo de hóquei
29: Eventos	71: Videogame
31: Comunidade	78: Publicadora de videogames
35: Políticos	79: Hardware de videogame
38: Disputa política	83: Partida de críquete
39: Jogo de basquete	84: Livro
40: Série esportiva	85: Gênero literário
43: Partida de futebol	86: Filme
44: Jogo de beisebol	87: Gênero de filme
45: Vertical de marca	88: Órgão político
46: Categoria de marca	89: Álbum musical
47: Marca	90: Estação de rádio
48: Produto	91: Podcast
54: Músico	92: Personalidade esportiva
55: Gênero musical	93: Técnico/treinador
56: Ator	94: Jornalista
58: Personalidade do entretenimento	95: Canal de TV [Entity Service]
60: Atleta	109: Tendências recorrentes
65: Vertical de interesses e hobbies	110: Contas virais
66: Categoria de interesses e hobbies	114: Show/concerto
67: Interesses e hobbies	115: Conferência de videogame
68: Jogo de hóquei	116: Torneio de videogame
71: Videogame	117: Festival de cinema
78: Publicadora de videogames	118: Premiação
79: Hardware de videogame	119: Feriado
83: Partida de críquete	120: Criador digital
84: Livro	122: Personagem fictício
85: Gênero literário	130: Franquia multimídia
86: Filme	131: Taxonomia unificada do Twitter
87: Gênero de filme	136: Personalidade de videogame
88: Órgão político	137: Time de eSports
89: Álbum musical	138: Jogador de eSports
90: Estação de rádio	139: Comunidade de fãs
91: Podcast	149: Liga de eSports
92: Personalidade esportiva	152: Comida
93: Técnico/treinador	155: Clima
94: Jornalista	156: Cidades
95: Canal de TV [Entity Service]	157: Faculdades e universidades
109: Tendências recorrentes	158: Pontos de interesse
110: Contas virais	159: Estados
114: Show/concerto	160: Países
115: Conferência de videogame	162: Exercício e fitness
116: Torneio de videogame	163: Viagem
117: Festival de cinema	164: Campos de estudo
118: Premiação	165: Tecnologia
119: Feriado	166: Ações
120: Criador digital	167: Animais
122: Personagem fictício	171: Notícias locais
130: Franquia multimídia	172: Programa de TV global
131: Taxonomia unificada do Twitter	173: Taxonomia de produtos do Google
136: Personalidade de videogame	174: Ativos digitais e cripto
137: Time de eSports	175: Eventos de emergência
138: Jogador de eSports

Nota: O Domínio 131 (Unified Twitter Taxonomy) refere-se à taxonomia de interesses voltada ao usuário (User-Facing Interest Taxonomy) da X. Essa taxonomia ajuda a alimentar recursos da plataforma, como Topics.

​

Solicitando annotations

​

Exemplo de requisição

curl --location --request GET 'https://api.x.com/2/tweets/1212092628029698048?tweet.fields=context_annotations,entities' --header 'Authorization: Bearer $BEARER_TOKEN'

​

Exemplo de resposta

{
    "data": {
        "context_annotations": [
            {
                "domain": {
                    "id": "119",
                    "name": "Holiday",
                    "description": "Feriados como Natal ou Halloween"
                },
                "entity": {
                    "id": "1186637514896920576",
                    "name": "Véspera de Ano Novo"
                }
            },
            {
                "domain": {
                    "id": "119",
                    "name": "Holiday",
                    "description": "Feriados como Natal ou Halloween"
                },
                "entity": {
                    "id": "1206982436287963136",
                    "name": "Feliz Ano Novo: Finalmente é 2020 em todos os lugares!",
                    "description": "Acompanhe fogos de artifício e outras celebrações enquanto pessoas ao redor do mundo entram no novo ano.\nFoto via @GettyImages"
                }
            },
            {
                "domain": {
                    "id": "45",
                    "name": "Vertical de Marca",
                    "description": "Entidades de nível superior que descrevem o setor de uma Marca"
                }
            },
            {
                "domain": {
                    "id": "46",
                    "name": "Categoria de Marca",
                    "description": "Categorias dentro de Verticais de Marca que restringem o escopo das Marcas"
                },
                "entity": {
                    "id": "781974596752842752",
                    "name": "Serviços"
                }
            },
            {
                "domain": {
                    "id": "47",
                    "name": "Marca",
                    "description": "Marcas e Empresas"
                },
                "entity": {
                    "id": "10045225402",
                    "name": "Twitter"
                }
            }
        ],
        "entities": {
            "annotations": [
                {
                    "start": 144,
                    "end": 150,
                    "probability": 0.626,
                    "type": "Product",
                    "normalized_text": "Twitter"
                }
            ],
            "urls": [
                {
                    "start": 222,
                    "end": 245,
                    "url": "https://t.co/yvxdK6aOo2",
                    "expanded_url": "https://x.com/LovesNandos/status/1211797914437259264/photo/1",
                    "display_url": "pic.x.com/yvxdK6aOo2"
                }
            ]
        },
        "id": "1212092628029698048",
        "text": "Acreditamos que a melhor versão futura da nossa API virá de construí-la com VOCÊ. Um brinde a mais um ótimo ano com todos que desenvolvem na plataforma do Twitter. Mal podemos esperar para continuar trabalhando com vocês no novo ano. https://t.co/yvxdK6aOo2"
    }
}

​

App de exemplo

Confira o Post Entity Extractor no Glitch para descobrir facilmente context annotations em Posts e ver como esse recurso funciona.

​

Perguntas frequentes

​

Anotações de contexto

As perguntas abaixo são específicas do elemento de anotações de contexto em anotações de Tweet. Para mais detalhes, consulte a página Visão geral.

Como funcionam as annotations de context do Twitter?

O X classifica Tweets semanticamente, o que significa que curamos listas de palavras-chave, hashtags e @handles relevantes para um determinado tópico. Se um Tweet contiver o texto que especificamos, ele será rotulado de forma apropriada. Isso difere de uma abordagem de aprendizado de máquina, na qual um modelo é treinado especificamente para classificar texto (neste caso, Tweets) e gerar uma pontuação de probabilidade junto com a saída/classificação.

Como posso saber se seus data são completos e confiáveis?

As annotations do X são selecionadas por especialistas no assunto, usando processos de pesquisa e QA aprimorados ao longo de vários anos. O processo conta com ferramentas personalizadas para escalar o rastreamento de data na medida em que conseguimos manter excelente precisão e recall. Além disso, nossos data são auditados regularmente por uma equipe interna, tendo alcançado uma pontuação de precisão de ~80% nos últimos trimestres.

Como você garante a precisão?

Os membros da equipe realizam controle de qualidade (QA) das nossas entidades diariamente para garantir alta precisão e recall. Além disso, nosso trabalho é auditado trimestralmente por uma equipe interna, que revisa manualmente 10.000 Tweets em todos os nossos domínios para calcular uma pontuação de precisão.

Como você decide o que acompanhar?

Para alguns domínios, como esportes e TV, contamos com ingestão automatizada para construir nosso grafo. No domínio de Notícias, acompanhamos data sobre histórias publicadas pela equipe do X Moments. Nos demais casos, a equipe utiliza uma variedade de métodos de pesquisa para identificar tópicos a serem monitorados que gerem um alto volume de conversas na plataforma.

Que suporte histórico está disponível com as annotations de Tweet?

O rastreamento de dados começa assim que uma entidade é publicada; portanto, não anotamos Tweets que foram publicados antes de a entidade passar a ser rastreada. Por exemplo, se uma marca/empresa emergente for adicionada à taxonomia, não anotaremos retroativamente Tweets sobre essa marca anteriores ao momento em que a anotação foi adicionada.

O Twitter consegue anotar Tweets em idiomas que não sejam o inglês? Se sim, quais idiomas e a cobertura de Tweets anotados muda?

Sim. A cobertura de idiomas pode variar conforme o domínio e o mercado. Inglês e japonês estão presentes na maioria das maiores entidades. A seguir, uma lista dos idiomas e principais mercados atualmente cobertos:

1. English (US, UK)
2. Japanese (Japan)
3. Portuguese (Brazil)
4. Spanish (Argentina, Mexico, Spain)
5. Hindi (India)
6. Arabic (Saudi Arabia)
7. Turkish (Turkey)
8. Indonesian (Indonesia)
9. Russian (Russia)
10. French (France)

Em breve (~H2 2021):

1. German (Germany)
2. Tamil (India)

A seguir, uma tabela dos 15 principais países, ordenados pelos maiores níveis de cobertura de Tweets anotados:

Classificação	Código do país	País	% de Tweets anotados
1	IN	Índia	41%
2	VN	Vietnã	36%
3	GB	Grã-Bretanha	36%
4	EC	Equador	35%
5	PE	Peru	33%
6	US	Estados Unidos	32%
7	CA	Canadá	32%
8	AU	Austrália	31%
9	JP	Japão	31%
10	PH	Filipinas	30%
11	SG	Singapura	30%
12	MY	Malásia	30%
13	MX	México	30%
14	GB	Grã-Bretanha	29%
15	NG	Nigéria	29%

Quais “semânticas” subjacentes o Twitter utiliza para anotar um Tweet?

As annotations de Tweet consistem nas seguintes semânticas para anotar um Tweet:

• Contas — podemos anotar tweets de um determinado handle ou que mencionem esse handle
• Hashtags
• Palavras‑chave/frases

Para clientes familiarizados com as APIs de stream filtrado, como o PowerTrack, as semânticas usadas por annotations são, em essência, semelhantes às regras booleanas definidas para filtrar um stream de Tweets. Se um Tweet atender às condições semânticas subjacentes, ele será marcado de acordo.

Por que alguns Tweets têm entidades associadas a eles enquanto outros não têm?

O objetivo é anotar o maior número possível de Tweets; no entanto, há vários motivos pelos quais alguns Tweets não são anotados:

• Alguns Tweets não têm riqueza semântica suficiente para serem rotulados e não podem ser marcados segundo nossas regras de anotação atuais
• Alguns Tweets não são relacionados a nenhum tópico
• O Tweet trata de um tópico muito efêmero que não está no nosso grafo
• Não cobrimos o idioma/mercado
• Cobrimos o idioma/mercado, mas está faltando um tópico ou um termo/conta/hashtag específico relacionado a um tópico que já acompanhamos

Quando há vários domínios (por exemplo, [3,30]), o Entity ID permanece o mesmo?

Uma entidade pode pertencer a vários domínios. Os ids de domínio podem mudar, mas o id da entidade permanece o mesmo. Donald Glover é uma pessoa (domínio 10), um ator (domínio 56) e um músico (domínio 54), mas o id da entidade dele continua sendo 875072662527029248.

Vocês têm um cronograma definido para o acompanhamento de séries/filmes? Em outras palavras, por quanto tempo uma série/um filme é acompanhado antes/depois do lançamento?

O monitoramento começa um mês antes do lançamento. Para grandes sucessos de bilheteria, como um filme da Marvel, podemos começar a monitorá-los assim que surgirem as primeiras provocações sobre um lançamento futuro.

Os filmes têm um filtro de localidade semelhante ao disponível para programas de TV?

Não.