data_for_seo/entity/dataforseo_labs/
google.rs

1//! Google-specific item models for the DataForSEO Labs API.
2
3use crate::entity::{
4    DataForSeoLabsKeywordData, DataForSeoLabsKeywordInfo, DataForSeoLabsMetrics,
5    DataForSeoLabsMetricsInfo, DataForSeoLabsRankedSerpElement, DataForSeoLabsSerpItem,
6};
7use serde::{Deserialize, Serialize};
8use serde_json::Value;
9use std::collections::HashMap;
10
11/// One keyword a target ranks for.
12/// See <https://docs.dataforseo.com/v3/dataforseo_labs/google/ranked_keywords/live/>.
13#[derive(Debug, Default, Serialize, Deserialize, Clone)]
14pub struct DataForSeoLabsRankedKeywordItem {
15    /// Search engine type (e.g. `"google"`).
16    pub se_type: Option<String>,
17    /// The ranked SERP position the target holds for this keyword.
18    pub ranked_serp_element: Option<DataForSeoLabsRankedSerpElement>,
19    /// Keyword metrics for the returned keyword.
20    pub keyword_data: Option<DataForSeoLabsKeywordData>,
21}
22
23/// One keyword related to a seed keyword, plus its expansion depth.
24/// See <https://docs.dataforseo.com/v3/dataforseo_labs/google/related_keywords/live/>.
25#[derive(Debug, Default, Serialize, Deserialize, Clone)]
26pub struct DataForSeoLabsRelatedKeywordItem {
27    /// Search engine type (e.g. `"google"`).
28    pub se_type: Option<String>,
29    /// Keyword metrics for the returned keyword.
30    pub keyword_data: Option<DataForSeoLabsKeywordData>,
31    /// Keyword expansion depth (0-4); higher values return more keywords.
32    pub depth: Option<i64>,
33    /// Keywords related to this keyword.
34    pub related_keywords: Option<Vec<String>>,
35}
36
37/// Search-intent classification of a single keyword.
38/// See <https://docs.dataforseo.com/v3/dataforseo_labs/google/search_intent/live/>.
39#[derive(Debug, Default, Serialize, Deserialize, Clone)]
40pub struct DataForSeoLabsSearchIntentItem {
41    /// Search engine type (e.g. `"google"`).
42    pub se_type: Option<String>,
43    /// Keyword the data relates to.
44    pub keyword: Option<String>,
45    /// Primary search-intent classification.
46    pub keyword_intent: Option<DataForSeoLabsKeywordIntent>,
47    /// Alternative search-intent classifications, by likelihood.
48    pub secondary_keyword_intents: Option<Vec<DataForSeoLabsKeywordIntent>>,
49}
50
51/// A labelled intent with its probability.
52/// See <https://docs.dataforseo.com/v3/dataforseo_labs/google/search_intent/live/>.
53#[derive(Debug, Default, Serialize, Deserialize, Clone)]
54pub struct DataForSeoLabsKeywordIntent {
55    /// Intent label: `"informational"`, `"navigational"`, `"commercial"`, or `"transactional"`.
56    pub label: Option<String>,
57    /// Confidence of the classification, from 0 to 1.
58    pub probability: Option<f64>,
59}
60
61/// Keyword difficulty score for a single keyword.
62/// See <https://docs.dataforseo.com/v3/dataforseo_labs/google/bulk_keyword_difficulty/live/>.
63#[derive(Debug, Default, Serialize, Deserialize, Clone)]
64pub struct DataForSeoLabsKeywordDifficultyItem {
65    /// Search engine type (e.g. `"google"`).
66    pub se_type: Option<String>,
67    /// Keyword the data relates to.
68    pub keyword: Option<String>,
69    /// Difficulty of ranking in the top 10, from 0 to 100.
70    pub keyword_difficulty: Option<i64>,
71}
72
73/// Historical monthly Google Ads metrics for a keyword.
74/// See <https://docs.dataforseo.com/v3/dataforseo_labs/google/historical_keyword_data/live/>.
75#[derive(Debug, Default, Serialize, Deserialize, Clone)]
76pub struct DataForSeoLabsHistoricalKeywordDataItem {
77    /// Search engine type (e.g. `"google"`).
78    pub se_type: Option<String>,
79    /// Keyword the data relates to.
80    pub keyword: Option<String>,
81    /// Location code (e.g. `2840`); alternative to `location_name`.
82    pub location_code: Option<i32>,
83    /// Language code (e.g. `"en"`); alternative to `language_name`.
84    pub language_code: Option<String>,
85    /// Metrics for each historical month.
86    pub history: Option<Vec<DataForSeoLabsKeywordHistory>>,
87}
88
89/// One month of historical keyword metrics.
90/// See <https://docs.dataforseo.com/v3/dataforseo_labs/google/historical_keyword_data/live/>.
91#[derive(Debug, Default, Serialize, Deserialize, Clone)]
92pub struct DataForSeoLabsKeywordHistory {
93    /// Year the data point refers to.
94    pub year: Option<i64>,
95    /// Month the data point refers to (1-12).
96    pub month: Option<i64>,
97    /// Google Ads keyword metrics.
98    pub keyword_info: Option<DataForSeoLabsKeywordInfo>,
99}
100
101/// A competing domain and its ranking metrics.
102/// See <https://docs.dataforseo.com/v3/dataforseo_labs/google/competitors_domain/live/>.
103#[derive(Debug, Default, Serialize, Deserialize, Clone)]
104pub struct DataForSeoLabsCompetitorItem {
105    /// Search engine type (e.g. `"google"`).
106    pub se_type: Option<String>,
107    /// Domain of the result.
108    pub domain: Option<String>,
109    /// Average SERP position across intersecting keywords.
110    pub avg_position: Option<f64>,
111    /// Sum of SERP positions across intersecting keywords.
112    pub sum_position: Option<i64>,
113    /// Number of keywords the targets have in common.
114    pub intersections: Option<i64>,
115    /// Metrics across all of the competitor's keywords.
116    pub full_domain_metrics: Option<DataForSeoLabsMetrics>,
117    /// Ranking and traffic metrics, grouped by SERP feature type.
118    pub metrics: Option<DataForSeoLabsMetrics>,
119    /// Metrics limited to keywords shared with the target.
120    pub competitor_metrics: Option<DataForSeoLabsMetrics>,
121}
122
123/// A domain competing for a set of keywords in the live SERP.
124/// See <https://docs.dataforseo.com/v3/dataforseo_labs/google/serp_competitors/live/>.
125#[derive(Debug, Default, Serialize, Deserialize, Clone)]
126pub struct DataForSeoLabsSerpCompetitorItem {
127    /// Search engine type (e.g. `"google"`).
128    pub se_type: Option<String>,
129    /// Domain of the result.
130    pub domain: Option<String>,
131    /// Average SERP position across intersecting keywords.
132    pub avg_position: Option<f64>,
133    /// Median SERP position across the keywords.
134    pub median_position: Option<f64>,
135    /// Visibility rating of the domain, from 0 to 1000.
136    pub rating: Option<i64>,
137    /// Estimated monthly traffic volume (CTR times search volume across ranking keywords).
138    pub etv: Option<f64>,
139    /// Number of keywords analyzed for the domain.
140    pub keywords_count: Option<i64>,
141    /// Share of possible SERP visibility captured, from 0 to 1.
142    pub visibility: Option<f64>,
143    /// Number of relevant SERP elements found for the domain.
144    pub relevant_serp_items: Option<i64>,
145    /// Positions the domain holds, keyed by keyword.
146    pub keywords_positions: Option<HashMap<String, Vec<i64>>>,
147}
148
149/// Ranking metrics of a domain in one location/language.
150/// See <https://docs.dataforseo.com/v3/dataforseo_labs/google/domain_rank_overview/live/>.
151#[derive(Debug, Default, Serialize, Deserialize, Clone)]
152pub struct DataForSeoLabsDomainMetricsItem {
153    /// Search engine type (e.g. `"google"`).
154    pub se_type: Option<String>,
155    /// Location code (e.g. `2840`); alternative to `location_name`.
156    pub location_code: Option<i32>,
157    /// Language code (e.g. `"en"`); alternative to `language_name`.
158    pub language_code: Option<String>,
159    /// Ranking and traffic metrics, grouped by SERP feature type.
160    pub metrics: Option<DataForSeoLabsMetrics>,
161}
162
163/// Estimated traffic metrics for a single target.
164/// See <https://docs.dataforseo.com/v3/dataforseo_labs/google/bulk_traffic_estimation/live/>.
165#[derive(Debug, Default, Serialize, Deserialize, Clone)]
166pub struct DataForSeoLabsTrafficEstimationItem {
167    /// Search engine type (e.g. `"google"`).
168    pub se_type: Option<String>,
169    /// Domain, subdomain, or webpage the request targets.
170    pub target: Option<String>,
171    /// Ranking and traffic metrics, grouped by SERP feature type.
172    pub metrics: Option<DataForSeoLabsMetrics>,
173}
174
175/// Ranking metrics of a subdomain.
176/// See <https://docs.dataforseo.com/v3/dataforseo_labs/google/subdomains/live/>.
177#[derive(Debug, Default, Serialize, Deserialize, Clone)]
178pub struct DataForSeoLabsSubdomainItem {
179    /// Search engine type (e.g. `"google"`).
180    pub se_type: Option<String>,
181    /// Subdomain the metrics belong to.
182    pub subdomain: Option<String>,
183    /// Ranking and traffic metrics, grouped by SERP feature type.
184    pub metrics: Option<DataForSeoLabsMetrics>,
185}
186
187/// Ranking metrics of a single page.
188/// See <https://docs.dataforseo.com/v3/dataforseo_labs/google/relevant_pages/live/>.
189#[derive(Debug, Default, Serialize, Deserialize, Clone)]
190pub struct DataForSeoLabsRelevantPageItem {
191    /// Search engine type (e.g. `"google"`).
192    pub se_type: Option<String>,
193    /// Absolute URL of the page.
194    pub page_address: Option<String>,
195    /// Ranking and traffic metrics, grouped by SERP feature type.
196    pub metrics: Option<DataForSeoLabsMetrics>,
197}
198
199/// A keyword both domains rank for, with each domain's SERP element.
200/// See <https://docs.dataforseo.com/v3/dataforseo_labs/google/domain_intersection/live/>.
201#[derive(Debug, Default, Serialize, Deserialize, Clone)]
202pub struct DataForSeoLabsDomainIntersectionItem {
203    /// Search engine type (e.g. `"google"`).
204    pub se_type: Option<String>,
205    /// Keyword metrics for the returned keyword.
206    pub keyword_data: Option<DataForSeoLabsKeywordData>,
207    /// SERP element the first domain holds for the keyword.
208    pub first_domain_serp_element: Option<DataForSeoLabsSerpItem>,
209    /// SERP element the second domain holds for the keyword.
210    pub second_domain_serp_element: Option<DataForSeoLabsSerpItem>,
211}
212
213/// A keyword with the SERP element each analyzed page holds for it.
214/// See <https://docs.dataforseo.com/v3/dataforseo_labs/google/page_intersection/live/>.
215#[derive(Debug, Default, Serialize, Deserialize, Clone)]
216pub struct DataForSeoLabsPageIntersectionItem {
217    /// Search engine type (e.g. `"google"`).
218    pub se_type: Option<String>,
219    /// Keyword metrics for the returned keyword.
220    pub keyword_data: Option<DataForSeoLabsKeywordData>,
221    /// SERP element each analyzed target holds for the keyword, keyed by target.
222    pub intersection_result: Option<HashMap<String, DataForSeoLabsSerpItem>>,
223}
224
225/// Ranking metrics of a domain for one historical month.
226/// See <https://docs.dataforseo.com/v3/dataforseo_labs/google/historical_rank_overview/live/>.
227#[derive(Debug, Default, Serialize, Deserialize, Clone)]
228pub struct DataForSeoLabsHistoricalRankOverviewItem {
229    /// Search engine type (e.g. `"google"`).
230    pub se_type: Option<String>,
231    /// Year the data point refers to.
232    pub year: Option<i64>,
233    /// Month the data point refers to (1-12).
234    pub month: Option<i64>,
235    /// Ranking and traffic metrics, grouped by SERP feature type.
236    pub metrics: Option<DataForSeoLabsMetrics>,
237}
238
239/// A historical SERP snapshot for a keyword.
240/// See <https://docs.dataforseo.com/v3/dataforseo_labs/google/historical_serps/live/>.
241#[derive(Debug, Default, Serialize, Deserialize, Clone)]
242pub struct DataForSeoLabsHistoricalSerpItem {
243    /// Search engine type (e.g. `"google"`).
244    pub se_type: Option<String>,
245    /// Keyword the data relates to.
246    pub keyword: Option<String>,
247    /// Type of SERP element (serialized as `type`).
248    #[serde(rename = "type")]
249    pub item_type: Option<String>,
250    /// Search-engine domain the SERP was collected from (e.g. `"google.com"`).
251    pub se_domain: Option<String>,
252    /// Location code (e.g. `2840`); alternative to `location_name`.
253    pub location_code: Option<i32>,
254    /// Language code (e.g. `"en"`); alternative to `language_name`.
255    pub language_code: Option<String>,
256    /// URL used to check the SERP.
257    pub check_url: Option<String>,
258    /// Date and time of the record (UTC).
259    pub datetime: Option<String>,
260    /// Spelling correction applied by the search engine, if any.
261    pub spell: Option<Value>,
262    /// SERP feature types to include (e.g. `"organic"`, `"paid"`).
263    pub item_types: Option<Vec<String>>,
264    /// Total number of results the search engine reported.
265    pub se_results_count: Option<i64>,
266    /// Number of items returned in `items`.
267    pub items_count: Option<i64>,
268    /// Result items.
269    pub items: Option<Vec<DataForSeoLabsSerpItem>>,
270}
271
272/// Ranking metrics of a domain for one product category.
273/// See <https://docs.dataforseo.com/v3/dataforseo_labs/google/categories_for_domain/live/>.
274#[derive(Debug, Default, Serialize, Deserialize, Clone)]
275pub struct DataForSeoLabsCategoryMetricsItem {
276    /// Search engine type (e.g. `"google"`).
277    pub se_type: Option<String>,
278    /// Product and service category codes for the keyword.
279    pub categories: Option<Vec<i64>>,
280    /// Ranking and traffic metrics, grouped by SERP feature type.
281    pub metrics: Option<DataForSeoLabsMetrics>,
282}
283
284/// Estimated traffic of a target for one historical month.
285/// See <https://docs.dataforseo.com/v3/dataforseo_labs/google/historical_bulk_traffic_estimation/live/>.
286#[derive(Debug, Default, Serialize, Deserialize, Clone)]
287pub struct DataForSeoLabsHistoricalMetricsInfo {
288    /// Year the data point refers to.
289    pub year: Option<i64>,
290    /// Month the data point refers to (1-12).
291    pub month: Option<i64>,
292    /// Estimated monthly traffic volume (CTR times search volume across ranking keywords).
293    pub etv: Option<f64>,
294    /// Number of SERPs containing the target for this feature type.
295    pub count: Option<i64>,
296}
297
298/// Historical traffic metrics grouped by SERP feature type.
299/// See <https://docs.dataforseo.com/v3/dataforseo_labs/google/historical_bulk_traffic_estimation/live/>.
300#[derive(Debug, Default, Serialize, Deserialize, Clone)]
301pub struct DataForSeoLabsHistoricalMetricsBundle {
302    /// Metrics for organic search results.
303    pub organic: Option<Vec<DataForSeoLabsHistoricalMetricsInfo>>,
304    /// Metrics for paid search results.
305    pub paid: Option<Vec<DataForSeoLabsHistoricalMetricsInfo>>,
306    /// Metrics for local pack results.
307    pub local_pack: Option<Vec<DataForSeoLabsHistoricalMetricsInfo>>,
308    /// Metrics for featured snippet results.
309    pub featured_snippet: Option<Vec<DataForSeoLabsHistoricalMetricsInfo>>,
310}
311
312/// Historical estimated traffic for a single target.
313/// See <https://docs.dataforseo.com/v3/dataforseo_labs/google/historical_bulk_traffic_estimation/live/>.
314#[derive(Debug, Default, Serialize, Deserialize, Clone)]
315pub struct DataForSeoLabsHistoricalTrafficEstimationItem {
316    /// Search engine type (e.g. `"google"`).
317    pub se_type: Option<String>,
318    /// Domain, subdomain, or webpage the request targets.
319    pub target: Option<String>,
320    /// Ranking and traffic metrics, grouped by SERP feature type.
321    pub metrics: Option<DataForSeoLabsHistoricalMetricsBundle>,
322}
323
324/// Product categories associated with a keyword.
325/// See <https://docs.dataforseo.com/v3/dataforseo_labs/google/categories_for_keywords/live/>.
326#[derive(Debug, Default, Serialize, Deserialize, Clone)]
327pub struct DataForSeoLabsCategoriesForKeywordsItem {
328    /// Keyword the data relates to.
329    pub keyword: Option<String>,
330    /// Product and service category codes for the keyword.
331    pub categories: Option<Vec<i64>>,
332}
333
334/// Ranking metrics of a domain collected for a set of product categories.
335/// See <https://docs.dataforseo.com/v3/dataforseo_labs/google/domain_metrics_by_categories/live/>.
336#[derive(Debug, Default, Serialize, Deserialize, Clone)]
337pub struct DataForSeoLabsDomainMetricsByCategoriesItem {
338    /// Search engine type (e.g. `"google"`).
339    pub se_type: Option<String>,
340    /// Category codes the domains were collected for.
341    pub top_categories: Option<Vec<i64>>,
342    /// Current organic estimated traffic volume of the domain.
343    pub organic_etv: Option<f64>,
344    /// Current number of organic SERPs containing the domain.
345    pub organic_count: Option<i64>,
346    /// Current number of lost organic ranked elements.
347    pub organic_is_lost: Option<i64>,
348    /// Current number of new organic ranked elements.
349    pub organic_is_new: Option<i64>,
350    /// Domain of the result.
351    pub domain: Option<String>,
352    /// Primary (registrable) domain.
353    pub main_domain: Option<String>,
354    /// Historical ranking metrics keyed by date and SERP feature type.
355    pub metrics_history: Option<HashMap<String, HashMap<String, DataForSeoLabsMetricsInfo>>>,
356    /// Change in metrics between the two compared dates, by SERP feature type.
357    pub metrics_difference: Option<HashMap<String, DataForSeoLabsMetricsInfo>>,
358}
data_for_seo/entity/dataforseo_labs/google.rs

data_for_seo/entity/dataforseo_labs/
google.rs
