data_for_seo/entity/ai_optimization/
llm_mentions.rs

1//! Models for the LLM Mentions sub-API.
2//!
3//! See <https://docs.dataforseo.com/v3/ai_optimization/llm_mentions/overview/>.
4
5use crate::entity::AiOptimizationMonthlySearch;
6use serde::{Deserialize, Serialize};
7use serde_json::Value;
8
9/// A grouped mention metric (`{ key, mentions, ai_search_volume }`).
10#[derive(Debug, Default, Serialize, Deserialize, Clone)]
11pub struct AiOptimizationMentionMetric {
12    /// Identifier of the group (e.g. a location, language or domain).
13    pub key: Option<String>,
14    /// Number of mentions within the group.
15    pub mentions: Option<i64>,
16    /// Aggregate AI search volume within the group.
17    pub ai_search_volume: Option<f64>,
18}
19
20/// Aggregate totals for a group of mentions.
21#[derive(Debug, Default, Serialize, Deserialize, Clone)]
22pub struct AiOptimizationMentionTotal {
23    /// Total number of mentions.
24    pub mentions: Option<i64>,
25    /// Total AI search volume.
26    pub ai_search_volume: Option<f64>,
27}
28
29/// Mention metrics grouped along every available dimension.
30///
31/// Shared by the aggregate and per-item breakdowns of the metrics and
32/// top-mentioned endpoints.
33#[derive(Debug, Default, Serialize, Deserialize, Clone)]
34pub struct AiOptimizationAggregatedMetrics {
35    /// Mentions broken down by location.
36    pub location: Option<Vec<AiOptimizationMentionMetric>>,
37    /// Mentions broken down by language.
38    pub language: Option<Vec<AiOptimizationMentionMetric>>,
39    /// Mentions broken down by platform (`chat_gpt`, `google`).
40    pub platform: Option<Vec<AiOptimizationMentionMetric>>,
41    /// Mentions broken down by domain cited as a source.
42    pub sources_domain: Option<Vec<AiOptimizationMentionMetric>>,
43    /// Mentions broken down by domain appearing in search results.
44    pub search_results_domain: Option<Vec<AiOptimizationMentionMetric>>,
45    /// Mentions broken down by brand-entity title.
46    pub brand_entities_title: Option<Vec<AiOptimizationMentionMetric>>,
47    /// Mentions broken down by brand-entity category.
48    pub brand_entities_category: Option<Vec<AiOptimizationMentionMetric>>,
49    /// Totals across every group.
50    pub total: Option<AiOptimizationMentionTotal>,
51}
52
53/// Source cited by an LLM answer inside a search-mentions result.
54///
55/// See <https://docs.dataforseo.com/v3/ai_optimization/llm_mentions/search/live/>.
56#[derive(Debug, Default, Serialize, Deserialize, Clone)]
57pub struct AiOptimizationMentionSource {
58    /// Text snippet extracted from the source.
59    pub snippet: Option<String>,
60    /// Display name of the source.
61    pub source_name: Option<String>,
62    /// URL of the source thumbnail image.
63    pub thumbnail: Option<String>,
64    /// Source content rendered as markdown.
65    pub markdown: Option<String>,
66    /// Position of the source within the answer.
67    pub position: Option<i64>,
68    /// Title of the source page.
69    pub title: Option<String>,
70    /// Domain of the source.
71    pub domain: Option<String>,
72    /// URL of the source.
73    pub url: Option<String>,
74    /// Publication date of the source, when available.
75    pub publication_date: Option<String>,
76}
77
78/// A single mention returned by the `search/live` endpoint.
79#[derive(Debug, Default, Serialize, Deserialize, Clone)]
80pub struct AiOptimizationLlmMention {
81    /// Platform the mention was found on (`chat_gpt`, `google`).
82    pub platform: Option<String>,
83    /// Name of the model that produced the answer.
84    pub model_name: Option<String>,
85    /// Location code the mention was recorded for.
86    pub location_code: Option<i32>,
87    /// Language code the mention was recorded for.
88    pub language_code: Option<String>,
89    /// The prompt/question that triggered the answer.
90    pub question: Option<String>,
91    /// The answer text (markdown format).
92    pub answer: Option<String>,
93    /// Sources cited by the answer.
94    pub sources: Option<Vec<AiOptimizationMentionSource>>,
95    /// Web search results attached to the answer (raw JSON).
96    pub search_results: Option<Value>,
97    /// AI search volume associated with the mention.
98    pub ai_search_volume: Option<f64>,
99    /// Monthly AI search-volume history for the mention.
100    pub monthly_searches: Option<Vec<AiOptimizationMonthlySearch>>,
101    /// UTC timestamp of the first recorded response.
102    pub first_response_at: Option<String>,
103    /// UTC timestamp of the most recent recorded response.
104    pub last_response_at: Option<String>,
105    /// Brand entities detected in the answer (raw JSON).
106    pub brand_entities: Option<Value>,
107    /// Fan-out queries derived from the prompt (raw JSON).
108    pub fan_out_queries: Option<Value>,
109}
110
111/// Result of the `search/live` endpoint.
112#[derive(Debug, Default, Serialize, Deserialize, Clone)]
113pub struct AiOptimizationLlmMentionsSearch {
114    /// Total number of mentions matching the request.
115    pub total_count: Option<i64>,
116    /// Offset of the first returned item.
117    pub current_offset: Option<i32>,
118    /// Token used to page beyond 20,000 results.
119    pub search_after_token: Option<String>,
120    /// Number of items in [`items`](Self::items).
121    pub items_count: Option<i64>,
122    /// The mentions returned for this page.
123    pub items: Option<Vec<AiOptimizationLlmMention>>,
124}
125
126/// A per-item mention breakdown.
127///
128/// One item shape covers `target_metrics`, `multi_target_metrics` and every
129/// `top_mentioned_*` endpoint; only the relevant identifier field
130/// (`domain`, `page`, `brand`, `brand_category` or `key`) is populated.
131#[derive(Debug, Default, Serialize, Deserialize, Clone)]
132pub struct AiOptimizationMentionItem {
133    /// Grouping identifier (used by `multi_target_metrics`).
134    pub key: Option<String>,
135    /// Domain the item refers to (`top_mentioned_domains`).
136    pub domain: Option<String>,
137    /// Page URL the item refers to (`top_mentioned_pages`).
138    pub page: Option<String>,
139    /// Brand the item refers to (`top_mentioned_brands`).
140    pub brand: Option<String>,
141    /// Brand category the item refers to (`top_mentioned_brand_categories`).
142    pub brand_category: Option<String>,
143    /// Mentions broken down by location.
144    pub location: Option<Vec<AiOptimizationMentionMetric>>,
145    /// Mentions broken down by language.
146    pub language: Option<Vec<AiOptimizationMentionMetric>>,
147    /// Mentions broken down by platform.
148    pub platform: Option<Vec<AiOptimizationMentionMetric>>,
149    /// Mentions broken down by domain cited as a source.
150    pub sources_domain: Option<Vec<AiOptimizationMentionMetric>>,
151    /// Mentions broken down by domain appearing in search results.
152    pub search_results_domain: Option<Vec<AiOptimizationMentionMetric>>,
153    /// Mentions broken down by brand-entity title.
154    pub brand_entities_title: Option<Vec<AiOptimizationMentionMetric>>,
155    /// Mentions broken down by brand-entity category.
156    pub brand_entities_category: Option<Vec<AiOptimizationMentionMetric>>,
157    /// Totals for this item.
158    pub total: Option<AiOptimizationMentionTotal>,
159}
160
161/// Result shared by the metrics and top-mentioned endpoints.
162///
163/// Covers `target_metrics`, `multi_target_metrics`, `top_mentioned_pages`,
164/// `top_mentioned_domains`, `top_mentioned_brands`,
165/// `top_mentioned_brand_categories` and their `_lite` variants.
166#[derive(Debug, Default, Serialize, Deserialize, Clone)]
167pub struct AiOptimizationLlmMentionsMetrics {
168    /// Total number of items matching the request.
169    pub total_count: Option<i64>,
170    /// Offset of the first returned item.
171    pub offset: Option<i32>,
172    /// Offset of the first returned item (alternate field name).
173    pub current_offset: Option<i32>,
174    /// Number of items in [`items`](Self::items).
175    pub items_count: Option<i64>,
176    /// Metrics aggregated across every returned item.
177    pub aggregated_metrics: Option<AiOptimizationAggregatedMetrics>,
178    /// Per-item metric breakdowns.
179    pub items: Option<Vec<AiOptimizationMentionItem>>,
180}
181
182/// A single point of a mentions timeseries.
183///
184/// Covers `historical`, `timeseries_delta` and `timeseries_new_lost`; only the
185/// fields relevant to the requested endpoint are populated.
186#[derive(Debug, Default, Serialize, Deserialize, Clone)]
187pub struct AiOptimizationMentionTimeseriesItem {
188    /// Date of the data point (`yyyy-mm-dd`).
189    pub date: Option<String>,
190    /// Year of the data point.
191    pub year: Option<i32>,
192    /// Month of the data point (`1`–`12`).
193    pub month: Option<i32>,
194    /// Number of mentions in the period (`historical`).
195    pub mentions: Option<i64>,
196    /// AI search volume in the period (`historical`).
197    pub ai_search_volume: Option<f64>,
198    /// Mentions gained in the period (`timeseries_new_lost`).
199    pub new_mentions: Option<i64>,
200    /// Mentions lost in the period (`timeseries_new_lost`).
201    pub lost_mentions: Option<i64>,
202    /// AI search volume gained in the period (`timeseries_new_lost`).
203    pub new_ai_search_volume: Option<f64>,
204    /// AI search volume lost in the period (`timeseries_new_lost`).
205    pub lost_ai_search_volume: Option<f64>,
206    /// Mention count difference from the previous period (`timeseries_delta`).
207    pub delta_mentions: Option<i64>,
208    /// AI search volume difference from the previous period (`timeseries_delta`).
209    pub delta_ai_search_volume: Option<f64>,
210}
211
212/// Result shared by the `historical`, `timeseries_delta` and
213/// `timeseries_new_lost` endpoints.
214#[derive(Debug, Default, Serialize, Deserialize, Clone)]
215pub struct AiOptimizationLlmMentionsTimeseries {
216    /// Number of items in [`items`](Self::items).
217    pub items_count: Option<i64>,
218    /// The timeseries data points.
219    pub items: Option<Vec<AiOptimizationMentionTimeseriesItem>>,
220    /// Start date of the series (`yyyy-mm-dd`).
221    pub date_from: Option<String>,
222    /// End date of the series (`yyyy-mm-dd`).
223    pub date_to: Option<String>,
224    /// Grouping range of the series (`day`, `week`, `month`, `year`).
225    pub group_range: Option<String>,
226}
data_for_seo/entity/ai_optimization/llm_mentions.rs

data_for_seo/entity/ai_optimization/
llm_mentions.rs
