From 08c7b3e68a9514dea76fb7f73094aebc0a7d21e3 Mon Sep 17 00:00:00 2001
From: Alexandre Teles <1757773+alexandreteles@users.noreply.github.com>
Date: Tue, 24 Sep 2024 01:11:22 -0300
Subject: [PATCH] docs: add video query information

---
 README.md          | 37 ++++++++++++++++++++++++++++++++++++-
 TikTok/__init__.py | 36 ++++++++++++++++++++++++++++++++++++
 2 files changed, 72 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 2266675..7be37f8 100644
--- a/README.md
+++ b/README.md
@@ -3,7 +3,7 @@
 TikTok is a Python library for interacting with the TikTok Research API.
 
 This library provides a simple and efficient way to access TikTok's API endpoints,
-allowing developers to retrieve user information, video details, and other data.
+allowing developers to retrieve user information, video details, and other relevant data.
 
 TikTok is built on top of the `httpx` library, which is a powerful and flexible HTTP library,
 and uses `orjson` for efficient JSON serialization and deserialization.
@@ -50,3 +50,38 @@ query = Query(auth)
 
 print(user_info)
 ```
+
+Given the complexity of video queries, this library provides a helper class to build them.
+It introduces some level of indirection and API inconsistency, but its introduction was a deliberate design choice to help users create queries
+that are easy to understand and modify without the need to manually write the JSON object or learn a dedicated DSL.
+
+```python
+# Example: Build a query to search for videos uploaded by "example_username" between August 1st and August 2nd, 2024.
+from TikTok.Query import Query
+from TikTok.ValidationModels.Video import (
+    VideoQueryRequestBuilder,
+    VideoQueryOperation,
+    VideoQueryFieldName,
+    VideoRegionCode,
+    VideoQueryFields,
+)
+
+query = Query(auth)
+
+video_query = VideoQueryRequestBuilder()
+
+request = (
+    video_query.start_date("20240801")
+    .end_date("20240802")
+    .max_count(100)
+    .and_(VideoQueryOperation.EQ, VideoQueryFieldName.username, ["example_username"])
+    .build()
+)
+
+video_query_response = await query.video.search(
+    request=request, fields=[VideoQueryFields.id, VideoQueryFields.voice_to_text]
+)
+
+```
+
+If you are interested in learning more about the underlying API, you can find the documentation here: [https://developers.tiktok.com/doc/research-api-specs-query-videos](https://developers.tiktok.com/doc/research-api-specs-query-videos)
diff --git a/TikTok/__init__.py b/TikTok/__init__.py
index a3531e9..732eb1c 100644
--- a/TikTok/__init__.py
+++ b/TikTok/__init__.py
@@ -49,4 +49,40 @@
 
 print(user_info)
 ```
+
+Given the complexity of video queries, this library provides a helper class to build them.
+It introduces some level of indirection and API inconsistency, but its introduction was a deliberate design choice to help users create queries
+that are easy to understand and modify without the need to manually write the JSON object or learn a dedicated DSL.
+
+```python
+# Example: Build a query to search for videos uploaded by "example_username" between August 1st and August 2nd, 2024.
+from TikTok.Query import Query
+from TikTok.ValidationModels.Video import (
+    VideoQueryRequestBuilder,
+    VideoQueryOperation,
+    VideoQueryFieldName,
+    VideoRegionCode,
+    VideoQueryFields,
+)
+
+query = Query(auth)
+
+video_query = VideoQueryRequestBuilder()
+
+request = (
+    video_query.start_date("20240801")
+    .end_date("20240802")
+    .max_count(100)
+    .and_(VideoQueryOperation.EQ, VideoQueryFieldName.username, ["example_username"])
+    .build()
+)
+
+video_query_response = await query.video.search(
+    request=request, fields=[VideoQueryFields.id, VideoQueryFields.voice_to_text]
+)
+
+```
+
+If you are interested in learning more about the underlying API, you can find the documentation here: [https://developers.tiktok.com/doc/research-api-specs-query-videos](https://developers.tiktok.com/doc/research-api-specs-query-videos)
+
 """