xapi-to 0.1.18 → 0.1.20

package/skills/xapi/guides/douyin.md

@@ -0,0 +1,297 @@
+# Douyin (抖音) Guide
+
+Complete guide for Douyin (抖音) operations via xAPI — user profiles, videos, comments, hot search, hashtags, music, and video statistics.
+
+> **Dynamic catalog:** These are database-registered third-party APIs under the `douyin` service. Exact action IDs, HTTP methods, parameters, and response fields can change. Run `search` and `get` before calling; the current schema wins. Examples below reflect one known GET-based version and keep `"method":"GET"` in the input for compatibility.
+
+## Contents
+
+- [User data](#user-data)
+- [Video data](#video-data)
+- [Video mixes](#video-mix-合集)
+- [Hot search](#hot-search-热搜)
+- [Hashtags](#hashtags)
+- [Music](#music)
+- [Common workflows](#common-workflows)
+- [Pagination](#pagination-patterns)
+- [API reference](#api-reference)
+- [Error handling](#error-handling)
+
+## User Data
+
+### Get user profile
+
+```bash
+npx xapi-to call douyin.api_v1_douyin_app_v3_handler__user__profile \
+  --input '{"method":"GET","params":{"sec_user_id":"<sec_user_id>"}}'
+```
+
+Requires `sec_user_id`. Returns user info at `data.data.user`.
+
+### Get user's videos
+
+```bash
+npx xapi-to call douyin.api_v1_douyin_app_v3_fetch__user__post__videos \
+  --input '{"method":"GET","params":{"sec_user_id":"<sec_user_id>","count":10}}'
+```
+
+Requires `sec_user_id`. Paginate with `max_cursor`. Optional: `sort_type`.
+
+### Get user's liked videos
+
+```bash
+npx xapi-to call douyin.api_v1_douyin_app_v3_fetch__user__like__videos \
+  --input '{"method":"GET","params":{"sec_user_id":"<sec_user_id>","counts":10}}'
+```
+
+Requires `sec_user_id`. Paginate with `max_cursor`. Note: the parameter is `counts` (with 's'), not `count`.
+
+### Get user fans list
+
+```bash
+npx xapi-to call douyin.api_v1_douyin_app_v3_fetch__user__fans__list \
+  --input '{"method":"GET","params":{"sec_user_id":"<sec_user_id>","count":20}}'
+```
+
+Paginate with `max_time`.
+
+### Get user series list
+
+```bash
+npx xapi-to call douyin.api_v1_douyin_app_v3_fetch__user__series__list \
+  --input '{"method":"GET","params":{"sec_user_id":"<sec_user_id>"}}'
+```
+
+## Video Data
+
+### Get video by ID
+
+```bash
+npx xapi-to call douyin.api_v1_douyin_app_v3_fetch__one__video \
+  --input '{"method":"GET","params":{"aweme_id":"<video_id>"}}'
+```
+
+Also available: V2 (`fetch__one__video__v2`) and V3 (`fetch__one__video__v3`, no copyright restrictions).
+
+### Get video by share URL
+
+```bash
+npx xapi-to call douyin.api_v1_douyin_app_v3_fetch__one__video__by__share__url \
+  --input '{"method":"GET","params":{"share_url":"https://v.douyin.com/xxxxx/"}}'
+```
+
+### Batch get videos
+
+```bash
+npx xapi-to call douyin.api_v1_douyin_app_v3_fetch__multi__video \
+  --input '{"method":"GET","params":{"aweme_ids":"id1,id2,id3"}}'
+```
+
+Also available: V2 (`fetch__multi__video__v2`).
+
+### Get video statistics
+
+```bash
+npx xapi-to call douyin.api_v1_douyin_app_v3_fetch__video__statistics \
+  --input '{"method":"GET","params":{"aweme_ids":"<video_id>"}}'
+```
+
+Returns like count, download count, play count, share count. Supports comma-separated IDs for batch queries.
+
+### Get high quality play URL
+
+```bash
+npx xapi-to call douyin.api_v1_douyin_app_v3_fetch__video__high__quality__play__url \
+  --input '{"method":"GET","params":{"aweme_id":"<video_id>"}}'
+```
+
+Returns the highest quality video play URL.
+
+### Get video comments
+
+```bash
+npx xapi-to call douyin.api_v1_douyin_app_v3_fetch__video__comments \
+  --input '{"method":"GET","params":{"aweme_id":"<video_id>","count":20,"cursor":0}}'
+```
+
+Paginate with `cursor`.
+
+### Get comment replies
+
+```bash
+npx xapi-to call douyin.api_v1_douyin_app_v3_fetch__video__comment__replies \
+  --input '{"method":"GET","params":{"item_id":"<video_id>","comment_id":"<comment_id>","count":20,"cursor":0}}'
+```
+
+## Video Mix (合集)
+
+### Get video mix detail
+
+```bash
+npx xapi-to call douyin.api_v1_douyin_app_v3_fetch__video__mix__detail \
+  --input '{"method":"GET","params":{"mix_id":"<mix_id>"}}'
+```
+
+### Get video mix post list
+
+```bash
+npx xapi-to call douyin.api_v1_douyin_app_v3_fetch__video__mix__post__list \
+  --input '{"method":"GET","params":{"mix_id":"<mix_id>","count":20,"cursor":0}}'
+```
+
+Paginate with `cursor`.
+
+### Get series detail
+
+```bash
+npx xapi-to call douyin.api_v1_douyin_app_v3_fetch__series__detail \
+  --input '{"method":"GET","params":{"series_id":"<series_id>"}}'
+```
+
+### Get series video list
+
+```bash
+npx xapi-to call douyin.api_v1_douyin_app_v3_fetch__series__video__list \
+  --input '{"method":"GET","params":{"series_id":"<series_id>"}}'
+```
+
+## Hot Search (热搜)
+
+### Get Douyin hot search list
+
+```bash
+npx xapi-to call douyin.api_v1_douyin_app_v3_fetch__hot__search__list \
+  --input '{"method":"GET","params":{}}'
+```
+
+Returns ~50 trending topics at `data.data.data.word_list[]`. Most entries have fields: `word` (topic title), `hot_value`, `view_count`, `event_time`, `position`. Pinned/top entries may only have `word`, `hot_value`, `view_count` without `event_time` or `position`.
+
+Optional: `board_type`, `board_sub_type` for different ranking categories.
+
+### Get brand hot search list
+
+```bash
+npx xapi-to call douyin.api_v1_douyin_app_v3_fetch__brand__hot__search__list \
+  --input '{"method":"GET","params":{}}'
+```
+
+### Get live hot search list
+
+```bash
+npx xapi-to call douyin.api_v1_douyin_app_v3_fetch__live__hot__search__list \
+  --input '{"method":"GET","params":{}}'
+```
+
+## Hashtags
+
+### Get hashtag details
+
+```bash
+npx xapi-to call douyin.api_v1_douyin_app_v3_fetch__hashtag__detail \
+  --input '{"method":"GET","params":{"ch_id":123456}}'
+```
+
+Note: `ch_id` is an **integer** for Douyin.
+
+### Get hashtag video list
+
+```bash
+npx xapi-to call douyin.api_v1_douyin_app_v3_fetch__hashtag__video__list \
+  --input '{"method":"GET","params":{"ch_id":"<hashtag_id>","count":20,"cursor":0}}'
+```
+
+Optional: `sort_type` — `0` = comprehensive, `1` = most likes, `2` = latest first.
+
+## Music
+
+### Get music details
+
+```bash
+npx xapi-to call douyin.api_v1_douyin_app_v3_fetch__music__detail \
+  --input '{"method":"GET","params":{"music_id":"<music_id>"}}'
+```
+
+### Get music video list
+
+```bash
+npx xapi-to call douyin.api_v1_douyin_app_v3_fetch__music__video__list \
+  --input '{"method":"GET","params":{"music_id":"<music_id>"}}'
+```
+
+### Get music hot search list
+
+```bash
+npx xapi-to call douyin.api_v1_douyin_app_v3_fetch__music__hot__search__list \
+  --input '{"method":"GET","params":{}}'
+```
+
+## Common Workflows
+
+### Track Douyin trending
+
+1. Hot search: `douyin...fetch__hot__search__list` → top 50 trending topics
+2. Brand hot search: `douyin...fetch__brand__hot__search__list` → brand trending
+3. Get video details for a trending topic
+
+### Research a Douyin creator
+
+1. Get profile: `douyin...handler__user__profile` with `sec_user_id` → user info
+2. Get videos: `douyin...fetch__user__post__videos` → browse recent posts
+3. Get stats: `douyin...fetch__video__statistics` → batch check engagement metrics
+
+### Analyze a Douyin video
+
+1. Get video: `douyin...fetch__one__video` with `aweme_id` → full video data
+2. Get stats: `douyin...fetch__video__statistics` → play count, likes, downloads, shares
+3. Read comments: `douyin...fetch__video__comments` → top comments
+4. Get replies: `douyin...fetch__video__comment__replies` → comment threads
+
+### Browse a video series
+
+1. Get series: `douyin...fetch__series__detail` or `douyin...fetch__video__mix__detail`
+2. List videos: `douyin...fetch__series__video__list` or `douyin...fetch__video__mix__post__list`
+
+## Pagination Patterns
+
+| Pattern | Endpoints | How to use |
+|---------|-----------|------------|
+| `max_cursor` | user videos, liked videos | Pass `max_cursor` from previous response |
+| `cursor` | comments, hashtag videos, mix post list | Pass `cursor` from previous response |
+| `max_time` | fans list | Pass `max_time` from previous response |
+
+## API Reference
+
+| API (prefix: `douyin.api_v1_douyin_app_v3_`) | Description | Key Params |
+|---|---|---|
+| `handler__user__profile` | Get user profile | `sec_user_id` |
+| `fetch__user__post__videos` | User's videos | `sec_user_id`, `count`, `max_cursor` |
+| `fetch__user__like__videos` | User's liked videos | `sec_user_id`, `counts`, `max_cursor` |
+| `fetch__user__fans__list` | User's fans | `sec_user_id`, `count`, `max_time` |
+| `fetch__user__series__list` | User's series | `sec_user_id` |
+| `fetch__one__video` | Single video | `aweme_id` |
+| `fetch__one__video__v2` | Single video V2 | `aweme_id` |
+| `fetch__one__video__v3` | Single video V3 (no copyright restrictions) | `aweme_id` |
+| `fetch__one__video__by__share__url` | Video by share URL | `share_url` |
+| `fetch__multi__video` | Batch get videos | `aweme_ids` |
+| `fetch__video__statistics` | Video stats (batch) | `aweme_ids` |
+| `fetch__video__high__quality__play__url` | High quality play URL | `aweme_id` |
+| `fetch__video__comments` | Video comments | `aweme_id`, `count`, `cursor` |
+| `fetch__video__comment__replies` | Comment replies | `item_id`, `comment_id`, `count`, `cursor` |
+| `fetch__video__mix__detail` | Video mix detail | `mix_id` |
+| `fetch__video__mix__post__list` | Video mix posts | `mix_id`, `count`, `cursor` |
+| `fetch__series__detail` | Series detail | `series_id` |
+| `fetch__series__video__list` | Series videos | `series_id` |
+| `fetch__hot__search__list` | Hot search list | `board_type`, `board_sub_type` |
+| `fetch__brand__hot__search__list` | Brand hot search | — |
+| `fetch__live__hot__search__list` | Live hot search | — |
+| `fetch__hashtag__detail` | Hashtag details | `ch_id` (integer) |
+| `fetch__hashtag__video__list` | Hashtag videos | `ch_id`, `count`, `cursor`, `sort_type` |
+| `fetch__music__detail` | Music details | `music_id` |
+| `fetch__music__video__list` | Music videos | `music_id` |
+| `fetch__music__hot__search__list` | Music hot search | — |
+
+## Error Handling
+
+- **Missing sec_user_id** → Douyin requires `sec_user_id` for most user-related endpoints; obtain it through other channels
+- **Empty results** → Check that `aweme_id`, `ch_id`, `mix_id`, or `music_id` is valid
+- **Pagination exhausted** → When `has_more` is `0` or `false`, no more pages available

package/skills/xapi/guides/google_search.md

@@ -0,0 +1,194 @@
+# Google Search Guide
+
+Complete guide for web search operations via xAPI — general search, realtime search, news, images, videos, scholar, maps, places, and shopping.
+
+All search endpoints are capability-type actions under the `web.search` namespace. Parameters are passed directly (no `"method"` or `"params"` wrapper needed).
+
+## Contents
+
+- [Common parameters](#common-parameters)
+- [Web search](#web-search)
+- [News, image, video, and scholar search](#news-search)
+- [Maps and places](#maps-search)
+- [Shopping search](#shopping-search)
+- [Common workflows](#common-workflows)
+- [Localization tips](#localization-tips)
+- [API reference](#api-reference)
+
+## Common Parameters
+
+All search capabilities accept `q`, `gl`, `hl`, and `page`. Most also accept `autocorrect`; `web.search.realtime` does not expose it and deliberately disables autocorrection. Run `get` before relying on optional parameters.
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `q` | string | **(required)** | Search query |
+| `gl` | string | `"us"` | Country code (e.g. `us`, `cn`, `jp`, `de`) |
+| `hl` | string | `"en"` | Language code (e.g. `en`, `zh`, `ja`, `de`) |
+| `page` | number | `1` | Page number for pagination |
+| `autocorrect` | boolean | `true` | Supported by every search capability except `web.search.realtime` |
+
+## Web Search
+
+### General web search
+
+```bash
+npx xapi-to call web.search --input '{"q":"OpenAI GPT-5","num":10}'
+```
+
+Additional parameters:
+- `num` — number of results to return (default 10)
+- `location` — location name for localized results
+
+Returns `data.organic[]` with `title`, `link`, `snippet`, and `position`. The declared response also includes optional `data.knowledgeGraph` and `data.relatedSearches[]`.
+
+### Realtime web search
+
+```bash
+npx xapi-to call web.search.realtime --input '{"q":"breaking news","timeRange":"day","num":10}'
+```
+
+For finding the latest content with time-based filtering.
+
+Additional parameters:
+- `timeRange` — time filter: `"hour"`, `"day"` (default), `"week"`, `"month"`, `"year"`
+- `num` — number of results (default 10)
+- `location` — location for localized results
+
+Returns `data.organic[]` with fields: `title`, `link`, `snippet`, `position`, `date`.
+
+## News Search
+
+```bash
+npx xapi-to call web.search.news --input '{"q":"AI regulation"}'
+```
+
+Search Google News for articles.
+
+Additional parameters:
+- `tbs` — date range filter: `"qdr:h"` (past hour), `"qdr:d"` (past 24h), `"qdr:w"` (past week), `"qdr:m"` (past month), `"qdr:y"` (past year)
+
+Returns `data.news[]` with fields: `title`, `link`, `snippet`, `date`, `source`, `imageUrl`.
+
+## Image Search
+
+```bash
+npx xapi-to call web.search.image --input '{"q":"aurora borealis"}'
+```
+
+Search Google Images.
+
+Additional parameters:
+- `tbs` — date range filter (same values as news)
+
+Returns `data.images[]` with fields: `title`, `imageUrl`, `imageWidth`, `imageHeight`, `thumbnailUrl`, `source`, `domain`, `link`.
+
+## Video Search
+
+```bash
+npx xapi-to call web.search.video --input '{"q":"machine learning tutorial"}'
+```
+
+Search Google Videos (primarily YouTube results).
+
+Additional parameters:
+- `tbs` — date range filter (same values as news)
+
+Returns `data.videos[]` with declared fields `title`, `link`, `snippet`, `channel`, `date`, and `duration`.
+
+## Scholar Search
+
+```bash
+npx xapi-to call web.search.scholar --input '{"q":"transformer architecture attention"}'
+```
+
+Search Google Scholar for academic papers and citations.
+
+Returns `data.organic[]` with declared fields `title`, `link`, `snippet`, `publicationInfo`, `citedBy`, and `year`.
+
+## Maps Search
+
+```bash
+npx xapi-to call web.search.maps --input '{"q":"coffee shop near Times Square"}'
+```
+
+Search Google Maps for locations and businesses.
+
+Additional parameters:
+- `ll` — latitude/longitude coordinates to center the search (e.g. `"@40.7455096,-74.0083012,14z"`)
+
+Returns `data.places[]` with declared fields `title`, `address`, `latitude`, `longitude`, `rating`, `ratingCount`, and `category`.
+
+## Places Search
+
+```bash
+npx xapi-to call web.search.places --input '{"q":"best ramen in Tokyo","gl":"jp"}'
+```
+
+Search for businesses and places with richer contact details. Use this capability when phone number or website is important.
+
+Additional parameters:
+- `location` — location name to scope the search (e.g. `"San Francisco, California, United States"`)
+- `ll` — latitude/longitude coordinates (e.g. `"@37.7749295,-122.4194155,14z"`)
+
+Returns `data.places[]` with declared fields `title`, `address`, `latitude`, `longitude`, `rating`, `ratingCount`, `category`, `phoneNumber`, and `website`.
+
+## Shopping Search
+
+```bash
+npx xapi-to call web.search.shopping --input '{"q":"mechanical keyboard"}'
+```
+
+Search Google Shopping for products and prices.
+
+Additional parameters:
+- `tbs` — date range filter
+- `location` — location affecting prices and availability
+
+Returns `data.shopping[]` with declared fields `title`, `source`, `link`, `price`, `rating`, `ratingCount`, and `imageUrl`.
+
+The upstream provider can return additional fields that are not part of the capability's declared schema. Treat them as opportunistic: inspect the current `get` output and actual response before depending on them.
+
+## Common Workflows
+
+### Research a topic
+
+1. Web search: `web.search` → get authoritative sources
+2. News search: `web.search.news` → get latest developments
+3. Scholar search: `web.search.scholar` → find academic papers
+
+### Monitor breaking news
+
+1. Realtime search: `web.search.realtime` with `timeRange: "hour"` → latest content
+2. News search: `web.search.news` with `tbs: "qdr:h"` → latest news articles
+
+### Find a local business
+
+1. Maps search: `web.search.maps` with `ll` coordinates → find nearby listings and coordinates
+2. Places search: `web.search.places` → add phone numbers and websites when the upstream provides them
+
+### Product research
+
+1. Shopping search: `web.search.shopping` → compare prices and ratings
+2. Web search: `web.search` with `"<product> review"` → find reviews
+
+## Localization Tips
+
+- Set `gl` (country) and `hl` (language) together for best results:
+  - Chinese results: `"gl":"cn","hl":"zh"`
+  - Japanese results: `"gl":"jp","hl":"ja"`
+  - German results: `"gl":"de","hl":"de"`
+- Use `location` (for `web.search`, `web.search.realtime`, `web.search.places`, `web.search.shopping`) for city-level localization
+
+## API Reference
+
+| Capability | Description | Result Field | Key Result Fields |
+|------------|-------------|--------------|-------------------|
+| `web.search` | General web search | `organic[]` | `title`, `link`, `snippet`, `position` |
+| `web.search.realtime` | Realtime web search | `organic[]` | `title`, `link`, `snippet`, `date` |
+| `web.search.news` | News articles | `news[]` | `title`, `link`, `source`, `date` |
+| `web.search.image` | Image search | `images[]` | `title`, `imageUrl`, `imageWidth`, `imageHeight` |
+| `web.search.video` | Video search | `videos[]` | `title`, `link`, `channel`, `duration` |
+| `web.search.scholar` | Academic papers | `organic[]` | `title`, `link`, `citedBy`, `year` |
+| `web.search.maps` | Map locations | `places[]` | `title`, `address`, `latitude`, `longitude`, `category` |
+| `web.search.places` | Detailed business listings | `places[]` | `title`, `address`, `category`, `phoneNumber`, `website` |
+| `web.search.shopping` | Product search | `shopping[]` | `title`, `price`, `source`, `rating`, `imageUrl` |