ss_tools/tutorials/step_4.rs
1//! # Step 4 - Available Endpoints
2//!
3//! This tutorial covers all available API endpoints in `ss-tools`.
4//!
5//! ## Paper Data APIs
6//!
7//! ### Query a Paper by Title
8//!
9//! Search for a single paper by title using [`SemanticScholar::query_a_paper_by_title`](crate::SemanticScholar::query_a_paper_by_title).
10//!
11//! ```rust
12//! # use anyhow::Result;
13//! # use ss_tools::{SemanticScholar, QueryParams};
14//! # #[tokio::main]
15//! # async fn main() -> Result<()> {
16//! let mut ss = SemanticScholar::new();
17//! let mut query_params = QueryParams::default();
18//! query_params.query_text("Attention Is All You Need");
19//!
20//! let paper = ss.query_a_paper_by_title(query_params, 5, 10).await?;
21//! println!("Paper: {:?}", paper.title);
22//! # Ok(())
23//! # }
24//! ```
25//!
26//! ### Query Multiple Papers by Title
27//!
28//! Search for multiple papers by title using [`SemanticScholar::query_papers_by_title`](crate::SemanticScholar::query_papers_by_title).
29//!
30//! ```rust,no_run
31//! # use anyhow::Result;
32//! # use ss_tools::{SemanticScholar, QueryParams};
33//! # #[tokio::main]
34//! # async fn main() -> Result<()> {
35//! let mut ss = SemanticScholar::new();
36//! let mut query_params = QueryParams::default();
37//! query_params.query_text("deep learning");
38//!
39//! let papers = ss.query_papers_by_title(query_params, 5, 10).await?;
40//! println!("Found {} papers", papers.len());
41//! # Ok(())
42//! # }
43//! ```
44//!
45//! ### Query Paper Details
46//!
47//! Get detailed information about a paper using [`SemanticScholar::query_paper_details`](crate::SemanticScholar::query_paper_details).
48//!
49//! ```rust
50//! # use anyhow::Result;
51//! # use ss_tools::{SemanticScholar, QueryParams};
52//! # use ss_tools::structs::PaperField;
53//! # #[tokio::main]
54//! # async fn main() -> Result<()> {
55//! let mut ss = SemanticScholar::new();
56//! let mut query_params = QueryParams::default();
57//! query_params.paper_id("204e3073870fae3d05bcbc2f6a8e263d9b72e776");
58//! query_params.fields(vec![
59//! PaperField::Title,
60//! PaperField::Abstract,
61//! PaperField::CitationCount,
62//! ]);
63//!
64//! let paper = ss.query_paper_details(query_params, 5, 10).await?;
65//! println!("Title: {:?}", paper.title);
66//! # Ok(())
67//! # }
68//! ```
69//!
70//! ### Query Paper Citations
71//!
72//! Get papers that cite a specific paper using [`SemanticScholar::query_paper_citations`](crate::SemanticScholar::query_paper_citations).
73//!
74//! ```rust
75//! # use anyhow::Result;
76//! # use ss_tools::{SemanticScholar, QueryParams};
77//! # use ss_tools::structs::PaperField;
78//! # #[tokio::main]
79//! # async fn main() -> Result<()> {
80//! let mut ss = SemanticScholar::new();
81//! let mut query_params = QueryParams::default();
82//! query_params.paper_id("204e3073870fae3d05bcbc2f6a8e263d9b72e776");
83//! query_params.fields(vec![PaperField::Title, PaperField::Year]);
84//!
85//! let citations = ss.query_paper_citations(query_params, 5, 10).await?;
86//! println!("Found {} citations", citations.data.len());
87//! # Ok(())
88//! # }
89//! ```
90//!
91//! ### Query Paper References
92//!
93//! Get papers referenced by a specific paper using [`SemanticScholar::query_paper_references`](crate::SemanticScholar::query_paper_references).
94//!
95//! ```rust
96//! # use anyhow::Result;
97//! # use ss_tools::{SemanticScholar, QueryParams};
98//! # use ss_tools::structs::PaperField;
99//! # #[tokio::main]
100//! # async fn main() -> Result<()> {
101//! let mut ss = SemanticScholar::new();
102//! let mut query_params = QueryParams::default();
103//! query_params.paper_id("204e3073870fae3d05bcbc2f6a8e263d9b72e776");
104//! query_params.fields(vec![PaperField::Title, PaperField::Year]);
105//!
106//! let references = ss.query_paper_references(query_params, 5, 10).await?;
107//! println!("Found {} references", references.data.len());
108//! # Ok(())
109//! # }
110//! ```
111//!
112//! ### Query Paper Authors
113//!
114//! Get authors of a specific paper using [`SemanticScholar::query_paper_authors`](crate::SemanticScholar::query_paper_authors).
115//!
116//! ```rust
117//! # use anyhow::Result;
118//! # use ss_tools::{SemanticScholar, QueryParams};
119//! # use ss_tools::structs::AuthorField;
120//! # #[tokio::main]
121//! # async fn main() -> Result<()> {
122//! let mut ss = SemanticScholar::new();
123//! let mut query_params = QueryParams::default();
124//! query_params.paper_id("204e3073870fae3d05bcbc2f6a8e263d9b72e776");
125//! query_params.author_fields(vec![
126//! AuthorField::Name,
127//! AuthorField::PaperCount,
128//! AuthorField::CitationCount,
129//! ]);
130//!
131//! let response = ss.query_paper_authors(query_params, 5, 10).await?;
132//! println!("Found {} authors", response.data.len());
133//! # Ok(())
134//! # }
135//! ```
136//!
137//! ## Author Data APIs
138//!
139//! ### Query Author Details
140//!
141//! Get detailed information about an author using [`SemanticScholar::query_author_details`](crate::SemanticScholar::query_author_details).
142//!
143//! ```rust
144//! # use anyhow::Result;
145//! # use ss_tools::{SemanticScholar, QueryParams};
146//! # use ss_tools::structs::AuthorField;
147//! # #[tokio::main]
148//! # async fn main() -> Result<()> {
149//! let mut ss = SemanticScholar::new();
150//! let mut query_params = QueryParams::default();
151//! query_params.paper_id("1741101"); // author_id is passed via paper_id field
152//! query_params.author_fields(vec![
153//! AuthorField::Name,
154//! AuthorField::PaperCount,
155//! AuthorField::CitationCount,
156//! AuthorField::HIndex,
157//! ]);
158//!
159//! let author = ss.query_author_details(query_params, 5, 10).await?;
160//! println!("Author: {:?}", author.name);
161//! # Ok(())
162//! # }
163//! ```
164//!
165//! ### Search Authors
166//!
167//! Search for authors by name using [`SemanticScholar::search_authors`](crate::SemanticScholar::search_authors).
168//!
169//! ```rust
170//! # use anyhow::Result;
171//! # use ss_tools::{SemanticScholar, QueryParams};
172//! # use ss_tools::structs::AuthorField;
173//! # #[tokio::main]
174//! # async fn main() -> Result<()> {
175//! let mut ss = SemanticScholar::new();
176//! let mut query_params = QueryParams::default();
177//! query_params.query_text("Geoffrey Hinton");
178//! query_params.author_fields(vec![
179//! AuthorField::Name,
180//! AuthorField::PaperCount,
181//! AuthorField::CitationCount,
182//! ]);
183//!
184//! let response = ss.search_authors(query_params, 5, 10).await?;
185//! println!("Found {} authors", response.data.len());
186//! # Ok(())
187//! # }
188//! ```
189//!
190//! ### Query Author Papers
191//!
192//! Get papers written by a specific author using [`SemanticScholar::query_author_papers`](crate::SemanticScholar::query_author_papers).
193//!
194//! ```rust
195//! # use anyhow::Result;
196//! # use ss_tools::{SemanticScholar, QueryParams};
197//! # use ss_tools::structs::PaperField;
198//! # #[tokio::main]
199//! # async fn main() -> Result<()> {
200//! let mut ss = SemanticScholar::new();
201//! let mut query_params = QueryParams::default();
202//! query_params.paper_id("1741101"); // author_id
203//! query_params.fields(vec![
204//! PaperField::Title,
205//! PaperField::Year,
206//! PaperField::CitationCount,
207//! ]);
208//! query_params.limit(10);
209//!
210//! let response = ss.query_author_papers(query_params, 5, 10).await?;
211//! println!("Found {} papers", response.data.len());
212//! # Ok(())
213//! # }
214//! ```
215//!
216//! ## Bulk Operations
217//!
218//! ### Bulk Query by IDs
219//!
220//! Get multiple papers at once using [`SemanticScholar::bulk_query_by_ids`](crate::SemanticScholar::bulk_query_by_ids).
221//!
222//! ```rust
223//! # use anyhow::Result;
224//! # use ss_tools::SemanticScholar;
225//! # use ss_tools::structs::PaperField;
226//! # #[tokio::main]
227//! # async fn main() -> Result<()> {
228//! let paper_ids = vec![
229//! "649def34f8be52c8b66281af98ae884c09aef38b",
230//! "ARXIV:2106.15928",
231//! ];
232//! let fields = vec![PaperField::Title, PaperField::CitationCount];
233//!
234//! let mut ss = SemanticScholar::new();
235//! let papers = ss.bulk_query_by_ids(paper_ids, fields, 5, 10).await?;
236//! println!("Retrieved {} papers", papers.len());
237//! # Ok(())
238//! # }
239//! ```