crawlora-tiktok 0.2.0 → 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: 77ed5b3f6f829bdcf660d50732e7c43ddd2e1bf10bd8c58b79f183458f38418d
4
- data.tar.gz: 336c1eabed9e96b56c27ef9ddefe8181fa077900a4f56ef22a4a0b55c4f15936
3
+ metadata.gz: c8035c0302d6b5888f9051e120fb3abc933d0258e58879da2961ec778eb71b35
4
+ data.tar.gz: 682bda66a6caf95e5e4b004e98a2bc83c5d1dec8d2aaa1ea251ba35bc4283ace
5
5
  SHA512:
6
- metadata.gz: a77354cb2d3158fcbc7c814bae3c254e76b055804f31b86b666449c5c3ae48aeaf0eff0e8ea12ebb7745c5b5876e935b8dc382c8b808276fb2aaf10f878f91e8
7
- data.tar.gz: db6d242b62b123e81203e1764fbcf32aba5b628b7ec8f311495a11a9329c5e11393c00c6073a65c77de8daef9c5856cce184f00b880148c244e19c70c998c04b
6
+ metadata.gz: fe0a640ff1aa784ff95468ebd7fa0aa8e9bd3e7b3d0b569aef2943fe4b4da16a518214a9c3a6262e53a4d1961d9fa0d8f0af19aa2d6ed7b7386ac99626851726
7
+ data.tar.gz: b478f54632b1b7f6592f8c088c8f96c887c823d06ee0885714a9a98488b9377f898d954dca91bda32307a443f01053f965971759738f19928394c4c129f53a99
data/README.md CHANGED
@@ -1,6 +1,6 @@
1
1
  # Crawlora TikTok API client for Ruby (`crawlora-tiktok`)
2
2
 
3
- This Ruby gem calls Crawlora's hosted TikTok API at `https://api.crawlora.net/api/v1`. It exposes 25 endpoints covering video, user, and hashtag search; profiles and posts; comments; trends; Creative Center; and Top Ads data; it does not call or scrape TikTok directly. Requests require your Crawlora API key and use your account's service plan.
3
+ This Ruby gem calls Crawlora's hosted TikTok API at `https://api.crawlora.net/api/v1`. It exposes 28 endpoints covering video, user, and hashtag search; profiles and posts; comments; trends; Creative Center; and Top Ads data; it does not call or scrape TikTok directly. Requests require your Crawlora API key and use your account's service plan.
4
4
 
5
5
  ## Install
6
6
 
@@ -20,7 +20,7 @@ puts result
20
20
  client.close
21
21
  ```
22
22
 
23
- Use an operation-specific method for normal calls. `request(operation_id, params = {}, response_type: :auto)` is available for every operation. `response_type: :text` returns raw response text. This gem includes 25 API operations.
23
+ Use an operation-specific method for normal calls. `request(operation_id, params = {}, response_type: :auto)` is available for every operation. `response_type: :text` returns raw response text. This gem includes 28 API operations.
24
24
 
25
25
  ```ruby
26
26
  client = Crawlora::Tiktok::Client.new(api_key: ENV.fetch("CRAWLORA_API_KEY"), timeout: 30)
@@ -38,11 +38,14 @@ Browse every route included in this gem. The [endpoint reference](https://github
38
38
  | --- | --- | --- | --- |
39
39
  | `GET` | `/tiktok/category` | `tiktok-category` | List TikTok explore categories |
40
40
  | `GET` | `/tiktok/comments` | `tiktok-video-comments` | Retrieve TikTok video comments |
41
+ | `GET` | `/tiktok/creative-center/filters` | `tiktok-creative-center-filters` | Retrieve TikTok Creative Center filter taxonomy |
41
42
  | `GET` | `/tiktok/creative-center/hashtags` | `tiktok-creative-center-hashtags` | Retrieve TikTok Creative Center trending hashtags |
43
+ | `GET` | `/tiktok/creative-center/top-content` | `tiktok-creative-center-top-content` | Retrieve TikTok Creative Center top content |
42
44
  | `GET` | `/tiktok/creative-center/videos` | `tiktok-creative-center-videos` | Retrieve TikTok Creative Center trending videos |
43
45
  | `GET` | `/tiktok/explore/{id}` | `tiktok-explore` | Retrieve the TikTok explore feed for a category |
44
46
  | `GET` | `/tiktok/hashtag/{name}` | `tiktok-challenge` | Retrieve TikTok hashtag details |
45
47
  | `GET` | `/tiktok/hashtags` | `tiktok-challenge-list` | Retrieve TikTok hashtag posts |
48
+ | `GET` | `/tiktok/mobile/feed` | `tiktok-mobile-feed` | Retrieve the TikTok mobile For You feed |
46
49
  | `GET` | `/tiktok/popular-trend/country-industry-meta` | `tiktok-popular-trend-country-industry-meta` | Retrieve TikTok popular-trend country and industry metadata |
47
50
  | `GET` | `/tiktok/post/{id}` | `tiktok-post` | Retrieve TikTok video details |
48
51
  | `GET` | `/tiktok/posts` | `tiktok-profile-post` | Retrieve posts from a TikTok profile |
@@ -19,17 +19,17 @@ module Crawlora
19
19
  end
20
20
 
21
21
  OPERATIONS = JSON.parse(<<~'JSON').freeze
22
- {"tiktok-category": {"bodyParam": null, "bodyRequired": false, "id": "tiktok-category", "method": "GET", "params": [], "path": "/tiktok/category", "pathParams": [], "produces": ["application/json"], "queryParams": [], "security": ["ApiKeyAuth"]}, "tiktok-challenge": {"bodyParam": null, "bodyRequired": false, "id": "tiktok-challenge", "method": "GET", "params": [{"description": "Hashtag name (e.g., 'christmas')", "in": "path", "name": "name", "required": true, "type": "string", "x-example": "christmas"}], "path": "/tiktok/hashtag/{name}", "pathParams": ["name"], "produces": ["application/json"], "queryParams": [], "security": ["ApiKeyAuth"]}, "tiktok-challenge-list": {"bodyParam": null, "bodyRequired": false, "id": "tiktok-challenge-list", "method": "GET", "params": [{"description": "Hashtag id returned by the hashtag detail endpoint", "in": "query", "name": "id", "required": true, "type": "string", "x-example": "3242"}, {"default": 0, "description": "Pagination cursor", "in": "query", "name": "cursor", "type": "integer"}], "path": "/tiktok/hashtags", "pathParams": [], "produces": ["application/json"], "queryParams": [{"in": "query", "name": "id", "required": true, "type": "string"}, {"in": "query", "name": "cursor", "type": "integer"}], "security": ["ApiKeyAuth"]}, "tiktok-creative-center-hashtags": {"bodyParam": null, "bodyRequired": false, "id": "tiktok-creative-center-hashtags", "method": "GET", "params": [{"description": "ISO-2 country code", "in": "query", "name": "country_code", "required": true, "type": "string", "x-example": "US"}, {"default": 7, "description": "Lookback window in days", "enum": [7, 30], "in": "query", "name": "period", "type": "integer"}], "path": "/tiktok/creative-center/hashtags", "pathParams": [], "produces": ["application/json"], "queryParams": [{"in": "query", "name": "country_code", "required": true, "type": "string"}, {"enum": ["7", "30"], "in": "query", "name": "period", "type": "integer"}], "security": ["ApiKeyAuth"]}, "tiktok-creative-center-videos": {"bodyParam": null, "bodyRequired": false, "id": "tiktok-creative-center-videos", "method": "GET", "params": [{"description": "ISO-2 country code", "in": "query", "name": "country_code", "required": true, "type": "string", "x-example": "US"}, {"default": 7, "description": "Lookback window in days", "enum": [7, 30], "in": "query", "name": "period", "type": "integer"}, {"default": "views", "description": "Sort order", "enum": ["views", "engagement", "six_second_views"], "in": "query", "name": "sort_by", "type": "string"}, {"description": "Content tag id to filter by", "in": "query", "name": "content_label_id", "type": "string", "x-example": "11015"}, {"default": false, "description": "Restrict to organic (non-paid) videos only", "in": "query", "name": "organic_only", "type": "boolean"}], "path": "/tiktok/creative-center/videos", "pathParams": [], "produces": ["application/json"], "queryParams": [{"in": "query", "name": "country_code", "required": true, "type": "string"}, {"enum": ["7", "30"], "in": "query", "name": "period", "type": "integer"}, {"enum": ["views", "engagement", "six_second_views"], "in": "query", "name": "sort_by", "type": "string"}, {"in": "query", "name": "content_label_id", "type": "string"}, {"in": "query", "name": "organic_only", "type": "boolean"}], "security": ["ApiKeyAuth"]}, "tiktok-explore": {"bodyParam": null, "bodyRequired": false, "id": "tiktok-explore", "method": "GET", "params": [{"description": "Category type id returned by the category endpoint", "in": "path", "name": "id", "required": true, "type": "integer", "x-example": 120}], "path": "/tiktok/explore/{id}", "pathParams": ["id"], "produces": ["application/json"], "queryParams": [], "security": ["ApiKeyAuth"]}, "tiktok-popular-trend-country-industry-meta": {"bodyParam": null, "bodyRequired": false, "id": "tiktok-popular-trend-country-industry-meta", "method": "GET", "params": [], "path": "/tiktok/popular-trend/country-industry-meta", "pathParams": [], "produces": ["application/json"], "queryParams": [], "security": ["ApiKeyAuth"]}, "tiktok-post": {"bodyParam": null, "bodyRequired": false, "id": "tiktok-post", "method": "GET", "params": [{"description": "TikTok video id", "in": "path", "name": "id", "required": true, "type": "string", "x-example": "7444278905264983342"}], "path": "/tiktok/post/{id}", "pathParams": ["id"], "produces": ["application/json"], "queryParams": [], "security": ["ApiKeyAuth"]}, "tiktok-profile": {"bodyParam": null, "bodyRequired": false, "id": "tiktok-profile", "method": "GET", "params": [{"description": "TikTok handle without the leading @", "in": "path", "name": "handler", "required": true, "type": "string", "x-example": "chatgpt"}], "path": "/tiktok/profile/{handler}", "pathParams": ["handler"], "produces": ["application/json"], "queryParams": [], "security": ["ApiKeyAuth"]}, "tiktok-profile-post": {"bodyParam": null, "bodyRequired": false, "id": "tiktok-profile-post", "method": "GET", "params": [{"description": "TikTok secUid for the profile", "in": "query", "name": "secUid", "required": true, "type": "string", "x-example": "MS4wLjABAAAAT4vq3vsh9X-Vb_WtV6tz4QWTbKjliTKCiK5DqnJNtQEA2RUveHb7UdnL7xgPK2HB"}, {"default": 0, "description": "Pagination cursor", "in": "query", "name": "cursor", "type": "integer"}, {"default": 0, "description": "Sort mode: 0 latest, 1 popular, 2 oldest", "enum": [0, 1, 2], "in": "query", "name": "sort_type", "type": "integer"}], "path": "/tiktok/posts", "pathParams": [], "produces": ["application/json"], "queryParams": [{"in": "query", "name": "secUid", "required": true, "type": "string"}, {"in": "query", "name": "cursor", "type": "integer"}, {"enum": ["0", "1", "2"], "in": "query", "name": "sort_type", "type": "integer"}], "security": ["ApiKeyAuth"]}, "tiktok-search": {"bodyParam": null, "bodyRequired": false, "id": "tiktok-search", "method": "GET", "params": [{"description": "Search keyword", "in": "query", "name": "keyword", "required": true, "type": "string", "x-example": "dance"}, {"default": 0, "description": "Pagination cursor", "in": "query", "name": "cursor", "type": "integer"}, {"default": 20, "description": "Result count, clamped to 50", "in": "query", "name": "count", "type": "integer"}], "path": "/tiktok/search", "pathParams": [], "produces": ["application/json"], "queryParams": [{"in": "query", "name": "keyword", "required": true, "type": "string"}, {"in": "query", "name": "cursor", "type": "integer"}, {"in": "query", "name": "count", "type": "integer"}], "security": ["ApiKeyAuth"]}, "tiktok-search-hashtag": {"bodyParam": null, "bodyRequired": false, "id": "tiktok-search-hashtag", "method": "GET", "params": [{"description": "Search keyword", "in": "query", "name": "keyword", "required": true, "type": "string", "x-example": "chatgpt"}, {"default": 0, "description": "Pagination cursor", "in": "query", "name": "cursor", "type": "integer"}, {"default": 20, "description": "Result count, clamped to 50", "in": "query", "name": "count", "type": "integer"}], "path": "/tiktok/search/hashtag", "pathParams": [], "produces": ["application/json"], "queryParams": [{"in": "query", "name": "keyword", "required": true, "type": "string"}, {"in": "query", "name": "cursor", "type": "integer"}, {"in": "query", "name": "count", "type": "integer"}], "security": ["ApiKeyAuth"]}, "tiktok-search-user": {"bodyParam": null, "bodyRequired": false, "id": "tiktok-search-user", "method": "GET", "params": [{"description": "Search keyword", "in": "query", "name": "keyword", "required": true, "type": "string", "x-example": "chatgpt"}, {"default": 0, "description": "Pagination cursor", "in": "query", "name": "cursor", "type": "integer"}], "path": "/tiktok/search/user", "pathParams": [], "produces": ["application/json"], "queryParams": [{"in": "query", "name": "keyword", "required": true, "type": "string"}, {"in": "query", "name": "cursor", "type": "integer"}], "security": ["ApiKeyAuth"]}, "tiktok-top-ads-analysis": {"bodyParam": null, "bodyRequired": false, "id": "tiktok-top-ads-analysis", "method": "GET", "params": [{"description": "Top Ads material id", "in": "query", "name": "material_id", "required": true, "type": "string", "x-example": "7130614705291427842"}, {"default": "retain_ctr", "description": "Interactive time analysis metric", "enum": ["retain_ctr", "retain_cvr", "click_cnt", "convert_cnt", "play_retain_cnt"], "in": "query", "name": "metric", "type": "string"}, {"default": 7, "description": "Percentile lookback period in days", "enum": [7, 30, 180], "in": "query", "name": "period_type", "type": "integer"}], "path": "/tiktok/top-ads/analysis", "pathParams": [], "produces": ["application/json"], "queryParams": [{"in": "query", "name": "material_id", "required": true, "type": "string"}, {"enum": ["retain_ctr", "retain_cvr", "click_cnt", "convert_cnt", "play_retain_cnt"], "in": "query", "name": "metric", "type": "string"}, {"enum": ["7", "30", "180"], "in": "query", "name": "period_type", "type": "integer"}], "security": ["ApiKeyAuth"]}, "tiktok-top-ads-detail": {"bodyParam": null, "bodyRequired": false, "id": "tiktok-top-ads-detail", "method": "GET", "params": [{"description": "Top Ads material id", "in": "query", "name": "material_id", "required": true, "type": "string", "x-example": "7631130810943897607"}], "path": "/tiktok/top-ads/detail", "pathParams": [], "produces": ["application/json"], "queryParams": [{"in": "query", "name": "material_id", "required": true, "type": "string"}], "security": ["ApiKeyAuth"]}, "tiktok-top-ads-filters": {"bodyParam": null, "bodyRequired": false, "id": "tiktok-top-ads-filters", "method": "GET", "params": [], "path": "/tiktok/top-ads/filters", "pathParams": [], "produces": ["application/json"], "queryParams": [], "security": ["ApiKeyAuth"]}, "tiktok-top-ads-list": {"bodyParam": null, "bodyRequired": false, "id": "tiktok-top-ads-list", "method": "GET", "params": [{"default": 30, "description": "Lookback period in days", "enum": [7, 30, 180], "in": "query", "name": "period", "type": "integer"}, {"default": 1, "description": "Page number", "in": "query", "minimum": 1, "name": "page", "type": "integer"}, {"default": 20, "description": "Maximum number of ads to return", "in": "query", "maximum": 100, "name": "limit", "type": "integer"}, {"default": "for_you", "description": "Sort order", "enum": ["for_you", "impression", "ctr", "play_2s_rate", "play_6s_rate", "cvr", "like"], "in": "query", "name": "order_by", "type": "string"}, {"description": "Country code or comma-separated country codes from /tiktok/top-ads/filters", "in": "query", "name": "country_code", "type": "string", "x-example": "US"}, {"description": "Brand or product keyword search", "in": "query", "name": "keyword", "type": "string", "x-example": "coffee"}, {"description": "Industry filter id or comma-separated ids from /tiktok/top-ads/filters", "in": "query", "name": "industry", "type": "string", "x-example": "23118000000"}, {"description": "Objective filter id or comma-separated ids from /tiktok/top-ads/filters", "in": "query", "name": "objective", "type": "string", "x-example": "3"}, {"description": "Ad language id or comma-separated ids from /tiktok/top-ads/filters", "in": "query", "name": "ad_language", "type": "string", "x-example": "en"}, {"description": "Pattern label id or comma-separated ids from /tiktok/top-ads/filters", "in": "query", "name": "pattern_label", "type": "string", "x-example": "10100100000"}, {"description": "Video duration bucket", "enum": ["time-2", "time-3", "time-4", "time-5", "time-6", "time-7"], "in": "query", "name": "duration", "type": "string"}, {"description": "Like percentile bucket id or comma-separated ids", "enum": ["1", "2", "3", "4", "5"], "in": "query", "name": "like", "type": "string"}, {"description": "Ad format id", "enum": ["1", "2"], "in": "query", "name": "ad_format", "type": "string"}], "path": "/tiktok/top-ads/list", "pathParams": [], "produces": ["application/json"], "queryParams": [{"enum": ["7", "30", "180"], "in": "query", "name": "period", "type": "integer"}, {"in": "query", "name": "page", "type": "integer"}, {"in": "query", "name": "limit", "type": "integer"}, {"enum": ["for_you", "impression", "ctr", "play_2s_rate", "play_6s_rate", "cvr", "like"], "in": "query", "name": "order_by", "type": "string"}, {"in": "query", "name": "country_code", "type": "string"}, {"in": "query", "name": "keyword", "type": "string"}, {"in": "query", "name": "industry", "type": "string"}, {"in": "query", "name": "objective", "type": "string"}, {"in": "query", "name": "ad_language", "type": "string"}, {"in": "query", "name": "pattern_label", "type": "string"}, {"enum": ["time-2", "time-3", "time-4", "time-5", "time-6", "time-7"], "in": "query", "name": "duration", "type": "string"}, {"enum": ["1", "2", "3", "4", "5"], "in": "query", "name": "like", "type": "string"}, {"enum": ["1", "2"], "in": "query", "name": "ad_format", "type": "string"}], "security": ["ApiKeyAuth"]}, "tiktok-top-ads-location-info": {"bodyParam": null, "bodyRequired": false, "id": "tiktok-top-ads-location-info", "method": "GET", "params": [{"default": 1, "description": "Optional upstream Creative Center module identifier; omitted or 0 defaults to 1, other nonzero IDs are passed through without local range validation", "in": "query", "name": "module", "type": "integer"}], "path": "/tiktok/top-ads/location-info", "pathParams": [], "produces": ["application/json"], "queryParams": [{"in": "query", "name": "module", "type": "integer"}], "security": ["ApiKeyAuth"]}, "tiktok-top-ads-locations": {"bodyParam": null, "bodyRequired": false, "id": "tiktok-top-ads-locations", "method": "GET", "params": [], "path": "/tiktok/top-ads/locations", "pathParams": [], "produces": ["application/json"], "queryParams": [], "security": ["ApiKeyAuth"]}, "tiktok-top-ads-recommend": {"bodyParam": null, "bodyRequired": false, "id": "tiktok-top-ads-recommend", "method": "GET", "params": [{"description": "Top Ads material id", "in": "query", "name": "material_id", "required": true, "type": "string", "x-example": "7631130810943897607"}, {"default": 1, "description": "Page number", "in": "query", "minimum": 1, "name": "page", "type": "integer"}, {"default": 20, "description": "Maximum number of ads to return", "in": "query", "maximum": 100, "name": "limit", "type": "integer"}], "path": "/tiktok/top-ads/recommend", "pathParams": [], "produces": ["application/json"], "queryParams": [{"in": "query", "name": "material_id", "required": true, "type": "string"}, {"in": "query", "name": "page", "type": "integer"}, {"in": "query", "name": "limit", "type": "integer"}], "security": ["ApiKeyAuth"]}, "tiktok-top-ads-safety": {"bodyParam": null, "bodyRequired": false, "id": "tiktok-top-ads-safety", "method": "GET", "params": [], "path": "/tiktok/top-ads/safety", "pathParams": [], "produces": ["application/json"], "queryParams": [], "security": ["ApiKeyAuth"]}, "tiktok-top-ads-spotlight": {"bodyParam": null, "bodyRequired": false, "id": "tiktok-top-ads-spotlight", "method": "GET", "params": [{"default": 1, "description": "Page number", "in": "query", "minimum": 1, "name": "page", "type": "integer"}, {"default": 20, "description": "Maximum number of ads to return", "in": "query", "maximum": 100, "name": "limit", "type": "integer"}], "path": "/tiktok/top-ads/spotlight", "pathParams": [], "produces": ["application/json"], "queryParams": [{"in": "query", "name": "page", "type": "integer"}, {"in": "query", "name": "limit", "type": "integer"}], "security": ["ApiKeyAuth"]}, "tiktok-top-ads-suggestions": {"bodyParam": null, "bodyRequired": false, "id": "tiktok-top-ads-suggestions", "method": "GET", "params": [{"default": 50, "description": "Maximum number of suggestions to return", "in": "query", "name": "count", "type": "integer"}, {"default": 1, "description": "Suggestion scenario id", "in": "query", "name": "scenario", "type": "integer"}], "path": "/tiktok/top-ads/suggestions", "pathParams": [], "produces": ["application/json"], "queryParams": [{"in": "query", "name": "count", "type": "integer"}, {"in": "query", "name": "scenario", "type": "integer"}], "security": ["ApiKeyAuth"]}, "tiktok-trending": {"bodyParam": null, "bodyRequired": false, "id": "tiktok-trending", "method": "GET", "params": [], "path": "/tiktok/trending", "pathParams": [], "produces": ["application/json"], "queryParams": [], "security": ["ApiKeyAuth"]}, "tiktok-video-comments": {"bodyParam": null, "bodyRequired": false, "id": "tiktok-video-comments", "method": "GET", "params": [{"description": "TikTok video id from the video URL", "in": "query", "name": "aweme_id", "required": true, "type": "string", "x-example": "7304809083817774382"}, {"default": 0, "description": "Pagination cursor", "in": "query", "name": "cursor", "type": "integer"}], "path": "/tiktok/comments", "pathParams": [], "produces": ["application/json"], "queryParams": [{"in": "query", "name": "aweme_id", "required": true, "type": "string"}, {"in": "query", "name": "cursor", "type": "integer"}], "security": ["ApiKeyAuth"]}}
22
+ {"tiktok-category": {"bodyParam": null, "bodyRequired": false, "id": "tiktok-category", "method": "GET", "params": [], "path": "/tiktok/category", "pathParams": [], "produces": ["application/json"], "queryParams": [], "security": ["ApiKeyAuth"]}, "tiktok-challenge": {"bodyParam": null, "bodyRequired": false, "id": "tiktok-challenge", "method": "GET", "params": [{"description": "Hashtag name (e.g., 'christmas')", "in": "path", "name": "name", "required": true, "type": "string", "x-example": "christmas"}], "path": "/tiktok/hashtag/{name}", "pathParams": ["name"], "produces": ["application/json"], "queryParams": [], "security": ["ApiKeyAuth"]}, "tiktok-challenge-list": {"bodyParam": null, "bodyRequired": false, "id": "tiktok-challenge-list", "method": "GET", "params": [{"description": "Hashtag id returned by the hashtag detail endpoint", "in": "query", "name": "id", "required": true, "type": "string", "x-example": "3242"}, {"default": 0, "description": "Pagination cursor", "in": "query", "name": "cursor", "type": "integer"}], "path": "/tiktok/hashtags", "pathParams": [], "produces": ["application/json"], "queryParams": [{"in": "query", "name": "id", "required": true, "type": "string"}, {"in": "query", "name": "cursor", "type": "integer"}], "security": ["ApiKeyAuth"]}, "tiktok-creative-center-filters": {"bodyParam": null, "bodyRequired": false, "id": "tiktok-creative-center-filters", "method": "GET", "params": [], "path": "/tiktok/creative-center/filters", "pathParams": [], "produces": ["application/json"], "queryParams": [], "security": ["ApiKeyAuth"]}, "tiktok-creative-center-hashtags": {"bodyParam": null, "bodyRequired": false, "id": "tiktok-creative-center-hashtags", "method": "GET", "params": [{"description": "ISO-2 country code", "in": "query", "name": "country_code", "required": true, "type": "string", "x-example": "US"}, {"default": 7, "description": "Lookback window in days", "enum": [7, 30, 90], "in": "query", "name": "period", "type": "integer"}, {"description": "Creative Center industry id to restrict the ranking to", "enum": ["10000000000", "11000000000", "12000000000", "13000000000", "14000000000", "15000000000", "17000000000", "18000000000", "19000000000", "21000000000", "22000000000", "23000000000", "24000000000", "25000000000", "26000000000", "27000000000", "28000000000", "29000000000"], "in": "query", "name": "industry_id", "type": "string", "x-example": "22000000000"}], "path": "/tiktok/creative-center/hashtags", "pathParams": [], "produces": ["application/json"], "queryParams": [{"in": "query", "name": "country_code", "required": true, "type": "string"}, {"enum": ["7", "30", "90"], "in": "query", "name": "period", "type": "integer"}, {"enum": ["10000000000", "11000000000", "12000000000", "13000000000", "14000000000", "15000000000", "17000000000", "18000000000", "19000000000", "21000000000", "22000000000", "23000000000", "24000000000", "25000000000", "26000000000", "27000000000", "28000000000", "29000000000"], "in": "query", "name": "industry_id", "type": "string"}], "security": ["ApiKeyAuth"]}, "tiktok-creative-center-top-content": {"bodyParam": null, "bodyRequired": false, "id": "tiktok-creative-center-top-content", "method": "GET", "params": [{"default": true, "description": "Include each object's top comments and comment-keyword counts", "in": "query", "name": "include_comments", "type": "boolean"}], "path": "/tiktok/creative-center/top-content", "pathParams": [], "produces": ["application/json"], "queryParams": [{"in": "query", "name": "include_comments", "type": "boolean"}], "security": ["ApiKeyAuth"]}, "tiktok-creative-center-videos": {"bodyParam": null, "bodyRequired": false, "id": "tiktok-creative-center-videos", "method": "GET", "params": [{"description": "ISO-2 country code", "in": "query", "name": "country_code", "required": true, "type": "string", "x-example": "US"}, {"default": 7, "description": "Lookback window in days", "enum": [7, 30], "in": "query", "name": "period", "type": "integer"}, {"default": "views", "description": "Sort order", "enum": ["views", "engagement", "six_second_views"], "in": "query", "name": "sort_by", "type": "string"}, {"description": "Deprecated: single content tag id; use content_label_ids instead", "in": "query", "name": "content_label_id", "type": "string", "x-example": "11015"}, {"collectionFormat": "multi", "description": "Content tag ids to filter by, repeatable; matches videos carrying any selected tag", "in": "query", "items": {"enum": ["11002", "11003", "11010", "11013", "11015"], "type": "string"}, "name": "content_label_ids", "type": "array", "x-example": "11003,11015"}, {"default": false, "description": "Restrict to organic (non-paid) videos only", "in": "query", "name": "organic_only", "type": "boolean"}], "path": "/tiktok/creative-center/videos", "pathParams": [], "produces": ["application/json"], "queryParams": [{"in": "query", "name": "country_code", "required": true, "type": "string"}, {"enum": ["7", "30"], "in": "query", "name": "period", "type": "integer"}, {"enum": ["views", "engagement", "six_second_views"], "in": "query", "name": "sort_by", "type": "string"}, {"in": "query", "name": "content_label_id", "type": "string"}, {"collectionFormat": "multi", "enum": ["11002", "11003", "11010", "11013", "11015"], "in": "query", "name": "content_label_ids", "type": "array"}, {"in": "query", "name": "organic_only", "type": "boolean"}], "security": ["ApiKeyAuth"]}, "tiktok-explore": {"bodyParam": null, "bodyRequired": false, "id": "tiktok-explore", "method": "GET", "params": [{"description": "Category type id returned by the category endpoint", "in": "path", "name": "id", "required": true, "type": "integer", "x-example": 120}], "path": "/tiktok/explore/{id}", "pathParams": ["id"], "produces": ["application/json"], "queryParams": [], "security": ["ApiKeyAuth"]}, "tiktok-mobile-feed": {"bodyParam": null, "bodyRequired": false, "id": "tiktok-mobile-feed", "method": "GET", "params": [{"default": 0, "description": "Videos to request (0 = app default, max 50)", "in": "query", "name": "count", "type": "integer"}, {"default": 0, "description": "Pagination cursor", "in": "query", "name": "cursor", "type": "integer"}], "path": "/tiktok/mobile/feed", "pathParams": [], "produces": ["application/json"], "queryParams": [{"in": "query", "name": "count", "type": "integer"}, {"in": "query", "name": "cursor", "type": "integer"}], "security": ["ApiKeyAuth"]}, "tiktok-popular-trend-country-industry-meta": {"bodyParam": null, "bodyRequired": false, "id": "tiktok-popular-trend-country-industry-meta", "method": "GET", "params": [], "path": "/tiktok/popular-trend/country-industry-meta", "pathParams": [], "produces": ["application/json"], "queryParams": [], "security": ["ApiKeyAuth"]}, "tiktok-post": {"bodyParam": null, "bodyRequired": false, "id": "tiktok-post", "method": "GET", "params": [{"description": "TikTok video id", "in": "path", "name": "id", "required": true, "type": "string", "x-example": "7444278905264983342"}], "path": "/tiktok/post/{id}", "pathParams": ["id"], "produces": ["application/json"], "queryParams": [], "security": ["ApiKeyAuth"]}, "tiktok-profile": {"bodyParam": null, "bodyRequired": false, "id": "tiktok-profile", "method": "GET", "params": [{"description": "TikTok handle without the leading @", "in": "path", "name": "handler", "required": true, "type": "string", "x-example": "chatgpt"}], "path": "/tiktok/profile/{handler}", "pathParams": ["handler"], "produces": ["application/json"], "queryParams": [], "security": ["ApiKeyAuth"]}, "tiktok-profile-post": {"bodyParam": null, "bodyRequired": false, "id": "tiktok-profile-post", "method": "GET", "params": [{"description": "TikTok secUid for the profile", "in": "query", "name": "secUid", "required": true, "type": "string", "x-example": "MS4wLjABAAAAT4vq3vsh9X-Vb_WtV6tz4QWTbKjliTKCiK5DqnJNtQEA2RUveHb7UdnL7xgPK2HB"}, {"default": 0, "description": "Pagination cursor", "in": "query", "name": "cursor", "type": "integer"}, {"default": 0, "description": "Sort mode: 0 latest, 1 popular, 2 oldest", "enum": [0, 1, 2], "in": "query", "name": "sort_type", "type": "integer"}], "path": "/tiktok/posts", "pathParams": [], "produces": ["application/json"], "queryParams": [{"in": "query", "name": "secUid", "required": true, "type": "string"}, {"in": "query", "name": "cursor", "type": "integer"}, {"enum": ["0", "1", "2"], "in": "query", "name": "sort_type", "type": "integer"}], "security": ["ApiKeyAuth"]}, "tiktok-search": {"bodyParam": null, "bodyRequired": false, "id": "tiktok-search", "method": "GET", "params": [{"description": "Search keyword", "in": "query", "name": "keyword", "required": true, "type": "string", "x-example": "dance"}, {"default": 0, "description": "Pagination cursor", "in": "query", "name": "cursor", "type": "integer"}, {"default": 20, "description": "Result count, clamped to 50", "in": "query", "name": "count", "type": "integer"}], "path": "/tiktok/search", "pathParams": [], "produces": ["application/json"], "queryParams": [{"in": "query", "name": "keyword", "required": true, "type": "string"}, {"in": "query", "name": "cursor", "type": "integer"}, {"in": "query", "name": "count", "type": "integer"}], "security": ["ApiKeyAuth"]}, "tiktok-search-hashtag": {"bodyParam": null, "bodyRequired": false, "id": "tiktok-search-hashtag", "method": "GET", "params": [{"description": "Search keyword", "in": "query", "name": "keyword", "required": true, "type": "string", "x-example": "chatgpt"}, {"default": 0, "description": "Pagination cursor", "in": "query", "name": "cursor", "type": "integer"}, {"default": 20, "description": "Result count, clamped to 50", "in": "query", "name": "count", "type": "integer"}], "path": "/tiktok/search/hashtag", "pathParams": [], "produces": ["application/json"], "queryParams": [{"in": "query", "name": "keyword", "required": true, "type": "string"}, {"in": "query", "name": "cursor", "type": "integer"}, {"in": "query", "name": "count", "type": "integer"}], "security": ["ApiKeyAuth"]}, "tiktok-search-user": {"bodyParam": null, "bodyRequired": false, "id": "tiktok-search-user", "method": "GET", "params": [{"description": "Search keyword", "in": "query", "name": "keyword", "required": true, "type": "string", "x-example": "chatgpt"}, {"default": 0, "description": "Pagination cursor", "in": "query", "name": "cursor", "type": "integer"}], "path": "/tiktok/search/user", "pathParams": [], "produces": ["application/json"], "queryParams": [{"in": "query", "name": "keyword", "required": true, "type": "string"}, {"in": "query", "name": "cursor", "type": "integer"}], "security": ["ApiKeyAuth"]}, "tiktok-top-ads-analysis": {"bodyParam": null, "bodyRequired": false, "id": "tiktok-top-ads-analysis", "method": "GET", "params": [{"description": "Top Ads material id", "in": "query", "name": "material_id", "required": true, "type": "string", "x-example": "7130614705291427842"}, {"default": "retain_ctr", "description": "Interactive time analysis metric", "enum": ["retain_ctr", "retain_cvr", "click_cnt", "convert_cnt", "play_retain_cnt"], "in": "query", "name": "metric", "type": "string"}, {"default": 7, "description": "Percentile lookback period in days", "enum": [7, 30, 180], "in": "query", "name": "period_type", "type": "integer"}], "path": "/tiktok/top-ads/analysis", "pathParams": [], "produces": ["application/json"], "queryParams": [{"in": "query", "name": "material_id", "required": true, "type": "string"}, {"enum": ["retain_ctr", "retain_cvr", "click_cnt", "convert_cnt", "play_retain_cnt"], "in": "query", "name": "metric", "type": "string"}, {"enum": ["7", "30", "180"], "in": "query", "name": "period_type", "type": "integer"}], "security": ["ApiKeyAuth"]}, "tiktok-top-ads-detail": {"bodyParam": null, "bodyRequired": false, "id": "tiktok-top-ads-detail", "method": "GET", "params": [{"description": "Top Ads material id", "in": "query", "name": "material_id", "required": true, "type": "string", "x-example": "7631130810943897607"}], "path": "/tiktok/top-ads/detail", "pathParams": [], "produces": ["application/json"], "queryParams": [{"in": "query", "name": "material_id", "required": true, "type": "string"}], "security": ["ApiKeyAuth"]}, "tiktok-top-ads-filters": {"bodyParam": null, "bodyRequired": false, "id": "tiktok-top-ads-filters", "method": "GET", "params": [], "path": "/tiktok/top-ads/filters", "pathParams": [], "produces": ["application/json"], "queryParams": [], "security": ["ApiKeyAuth"]}, "tiktok-top-ads-list": {"bodyParam": null, "bodyRequired": false, "id": "tiktok-top-ads-list", "method": "GET", "params": [{"default": 30, "description": "Lookback period in days", "enum": [7, 30, 180], "in": "query", "name": "period", "type": "integer"}, {"default": 1, "description": "Page number", "in": "query", "minimum": 1, "name": "page", "type": "integer"}, {"default": 20, "description": "Maximum number of ads to return", "in": "query", "maximum": 100, "name": "limit", "type": "integer"}, {"default": "for_you", "description": "Sort order", "enum": ["for_you", "impression", "ctr", "play_2s_rate", "play_6s_rate", "cvr", "like"], "in": "query", "name": "order_by", "type": "string"}, {"description": "Country code or comma-separated country codes from /tiktok/top-ads/filters", "in": "query", "name": "country_code", "type": "string", "x-example": "US"}, {"description": "Brand or product keyword search", "in": "query", "name": "keyword", "type": "string", "x-example": "coffee"}, {"description": "Industry filter id or comma-separated ids from /tiktok/top-ads/filters", "in": "query", "name": "industry", "type": "string", "x-example": "23118000000"}, {"description": "Objective filter id or comma-separated ids from /tiktok/top-ads/filters", "in": "query", "name": "objective", "type": "string", "x-example": "3"}, {"description": "Ad language id or comma-separated ids from /tiktok/top-ads/filters", "in": "query", "name": "ad_language", "type": "string", "x-example": "en"}, {"description": "Pattern label id or comma-separated ids from /tiktok/top-ads/filters", "in": "query", "name": "pattern_label", "type": "string", "x-example": "10100100000"}, {"description": "Video duration bucket", "enum": ["time-2", "time-3", "time-4", "time-5", "time-6", "time-7"], "in": "query", "name": "duration", "type": "string"}, {"description": "Like percentile bucket id or comma-separated ids", "enum": ["1", "2", "3", "4", "5"], "in": "query", "name": "like", "type": "string"}, {"description": "Ad format id", "enum": ["1", "2"], "in": "query", "name": "ad_format", "type": "string"}], "path": "/tiktok/top-ads/list", "pathParams": [], "produces": ["application/json"], "queryParams": [{"enum": ["7", "30", "180"], "in": "query", "name": "period", "type": "integer"}, {"in": "query", "name": "page", "type": "integer"}, {"in": "query", "name": "limit", "type": "integer"}, {"enum": ["for_you", "impression", "ctr", "play_2s_rate", "play_6s_rate", "cvr", "like"], "in": "query", "name": "order_by", "type": "string"}, {"in": "query", "name": "country_code", "type": "string"}, {"in": "query", "name": "keyword", "type": "string"}, {"in": "query", "name": "industry", "type": "string"}, {"in": "query", "name": "objective", "type": "string"}, {"in": "query", "name": "ad_language", "type": "string"}, {"in": "query", "name": "pattern_label", "type": "string"}, {"enum": ["time-2", "time-3", "time-4", "time-5", "time-6", "time-7"], "in": "query", "name": "duration", "type": "string"}, {"enum": ["1", "2", "3", "4", "5"], "in": "query", "name": "like", "type": "string"}, {"enum": ["1", "2"], "in": "query", "name": "ad_format", "type": "string"}], "security": ["ApiKeyAuth"]}, "tiktok-top-ads-location-info": {"bodyParam": null, "bodyRequired": false, "id": "tiktok-top-ads-location-info", "method": "GET", "params": [{"default": 1, "description": "Optional upstream Creative Center module identifier; omitted or 0 defaults to 1, other nonzero IDs are passed through without local range validation", "in": "query", "name": "module", "type": "integer"}], "path": "/tiktok/top-ads/location-info", "pathParams": [], "produces": ["application/json"], "queryParams": [{"in": "query", "name": "module", "type": "integer"}], "security": ["ApiKeyAuth"]}, "tiktok-top-ads-locations": {"bodyParam": null, "bodyRequired": false, "id": "tiktok-top-ads-locations", "method": "GET", "params": [], "path": "/tiktok/top-ads/locations", "pathParams": [], "produces": ["application/json"], "queryParams": [], "security": ["ApiKeyAuth"]}, "tiktok-top-ads-recommend": {"bodyParam": null, "bodyRequired": false, "id": "tiktok-top-ads-recommend", "method": "GET", "params": [{"description": "Top Ads material id", "in": "query", "name": "material_id", "required": true, "type": "string", "x-example": "7631130810943897607"}, {"default": 1, "description": "Page number", "in": "query", "minimum": 1, "name": "page", "type": "integer"}, {"default": 20, "description": "Maximum number of ads to return", "in": "query", "maximum": 100, "name": "limit", "type": "integer"}], "path": "/tiktok/top-ads/recommend", "pathParams": [], "produces": ["application/json"], "queryParams": [{"in": "query", "name": "material_id", "required": true, "type": "string"}, {"in": "query", "name": "page", "type": "integer"}, {"in": "query", "name": "limit", "type": "integer"}], "security": ["ApiKeyAuth"]}, "tiktok-top-ads-safety": {"bodyParam": null, "bodyRequired": false, "id": "tiktok-top-ads-safety", "method": "GET", "params": [], "path": "/tiktok/top-ads/safety", "pathParams": [], "produces": ["application/json"], "queryParams": [], "security": ["ApiKeyAuth"]}, "tiktok-top-ads-spotlight": {"bodyParam": null, "bodyRequired": false, "id": "tiktok-top-ads-spotlight", "method": "GET", "params": [{"default": 1, "description": "Page number", "in": "query", "minimum": 1, "name": "page", "type": "integer"}, {"default": 20, "description": "Maximum number of ads to return", "in": "query", "maximum": 100, "name": "limit", "type": "integer"}], "path": "/tiktok/top-ads/spotlight", "pathParams": [], "produces": ["application/json"], "queryParams": [{"in": "query", "name": "page", "type": "integer"}, {"in": "query", "name": "limit", "type": "integer"}], "security": ["ApiKeyAuth"]}, "tiktok-top-ads-suggestions": {"bodyParam": null, "bodyRequired": false, "id": "tiktok-top-ads-suggestions", "method": "GET", "params": [{"default": 50, "description": "Maximum number of suggestions to return", "in": "query", "name": "count", "type": "integer"}, {"default": 1, "description": "Suggestion scenario id", "in": "query", "name": "scenario", "type": "integer"}], "path": "/tiktok/top-ads/suggestions", "pathParams": [], "produces": ["application/json"], "queryParams": [{"in": "query", "name": "count", "type": "integer"}, {"in": "query", "name": "scenario", "type": "integer"}], "security": ["ApiKeyAuth"]}, "tiktok-trending": {"bodyParam": null, "bodyRequired": false, "id": "tiktok-trending", "method": "GET", "params": [], "path": "/tiktok/trending", "pathParams": [], "produces": ["application/json"], "queryParams": [], "security": ["ApiKeyAuth"]}, "tiktok-video-comments": {"bodyParam": null, "bodyRequired": false, "id": "tiktok-video-comments", "method": "GET", "params": [{"description": "TikTok video id from the video URL", "in": "query", "name": "aweme_id", "required": true, "type": "string", "x-example": "7304809083817774382"}, {"default": 0, "description": "Pagination cursor", "in": "query", "name": "cursor", "type": "integer"}], "path": "/tiktok/comments", "pathParams": [], "produces": ["application/json"], "queryParams": [{"in": "query", "name": "aweme_id", "required": true, "type": "string"}, {"in": "query", "name": "cursor", "type": "integer"}], "security": ["ApiKeyAuth"]}}
23
23
  JSON
24
24
  OPERATION_IDS = JSON.parse(<<~'JSON').freeze
25
- ["tiktok-category", "tiktok-challenge", "tiktok-challenge-list", "tiktok-creative-center-hashtags", "tiktok-creative-center-videos", "tiktok-explore", "tiktok-popular-trend-country-industry-meta", "tiktok-post", "tiktok-profile", "tiktok-profile-post", "tiktok-search", "tiktok-search-hashtag", "tiktok-search-user", "tiktok-top-ads-analysis", "tiktok-top-ads-detail", "tiktok-top-ads-filters", "tiktok-top-ads-list", "tiktok-top-ads-location-info", "tiktok-top-ads-locations", "tiktok-top-ads-recommend", "tiktok-top-ads-safety", "tiktok-top-ads-spotlight", "tiktok-top-ads-suggestions", "tiktok-trending", "tiktok-video-comments"]
25
+ ["tiktok-category", "tiktok-challenge", "tiktok-challenge-list", "tiktok-creative-center-filters", "tiktok-creative-center-hashtags", "tiktok-creative-center-top-content", "tiktok-creative-center-videos", "tiktok-explore", "tiktok-mobile-feed", "tiktok-popular-trend-country-industry-meta", "tiktok-post", "tiktok-profile", "tiktok-profile-post", "tiktok-search", "tiktok-search-hashtag", "tiktok-search-user", "tiktok-top-ads-analysis", "tiktok-top-ads-detail", "tiktok-top-ads-filters", "tiktok-top-ads-list", "tiktok-top-ads-location-info", "tiktok-top-ads-locations", "tiktok-top-ads-recommend", "tiktok-top-ads-safety", "tiktok-top-ads-spotlight", "tiktok-top-ads-suggestions", "tiktok-trending", "tiktok-video-comments"]
26
26
  JSON
27
27
  OPERATION_COUNT = OPERATION_IDS.length
28
28
 
29
29
  class Client
30
30
  attr_reader :base_url
31
31
 
32
- def initialize(api_key: ENV["CRAWLORA_API_KEY"], base_url: "https://api.crawlora.net/api/v1", timeout: 30, user_agent: "crawlora-tiktok-ruby/0.2.0", transport: nil)
32
+ def initialize(api_key: ENV["CRAWLORA_API_KEY"], base_url: "https://api.crawlora.net/api/v1", timeout: 30, user_agent: "crawlora-tiktok-ruby/0.3.0", transport: nil)
33
33
  @api_key = api_key
34
34
  @base_url = base_url.to_s.sub(%r{/+$}, "")
35
35
  @timeout = Float(timeout)
@@ -122,10 +122,18 @@ module Crawlora
122
122
  response_type = params.delete(:response_type) || params.delete(:_response_type) || :auto
123
123
  request('tiktok-video-comments', params, response_type: response_type)
124
124
  end
125
+ define_method('creative_center_filters') do |**params|
126
+ response_type = params.delete(:response_type) || params.delete(:_response_type) || :auto
127
+ request('tiktok-creative-center-filters', params, response_type: response_type)
128
+ end
125
129
  define_method('creative_center_hashtags') do |**params|
126
130
  response_type = params.delete(:response_type) || params.delete(:_response_type) || :auto
127
131
  request('tiktok-creative-center-hashtags', params, response_type: response_type)
128
132
  end
133
+ define_method('creative_center_top_content') do |**params|
134
+ response_type = params.delete(:response_type) || params.delete(:_response_type) || :auto
135
+ request('tiktok-creative-center-top-content', params, response_type: response_type)
136
+ end
129
137
  define_method('creative_center_videos') do |**params|
130
138
  response_type = params.delete(:response_type) || params.delete(:_response_type) || :auto
131
139
  request('tiktok-creative-center-videos', params, response_type: response_type)
@@ -142,6 +150,10 @@ module Crawlora
142
150
  response_type = params.delete(:response_type) || params.delete(:_response_type) || :auto
143
151
  request('tiktok-challenge-list', params, response_type: response_type)
144
152
  end
153
+ define_method('mobile_feed') do |**params|
154
+ response_type = params.delete(:response_type) || params.delete(:_response_type) || :auto
155
+ request('tiktok-mobile-feed', params, response_type: response_type)
156
+ end
145
157
  define_method('popular_trend_country_industry_meta') do |**params|
146
158
  response_type = params.delete(:response_type) || params.delete(:_response_type) || :auto
147
159
  request('tiktok-popular-trend-country-industry-meta', params, response_type: response_type)
@@ -1,5 +1,5 @@
1
1
  module Crawlora
2
2
  module Tiktok
3
- VERSION = "0.2.0"
3
+ VERSION = "0.3.0"
4
4
  end
5
5
  end
metadata CHANGED
@@ -1,18 +1,18 @@
1
1
  --- !ruby/object:Gem::Specification
2
2
  name: crawlora-tiktok
3
3
  version: !ruby/object:Gem::Version
4
- version: 0.2.0
4
+ version: 0.3.0
5
5
  platform: ruby
6
6
  authors:
7
7
  - Crawlora
8
8
  autorequire:
9
9
  bindir: bin
10
10
  cert_chain: []
11
- date: 2026-10-14 00:00:00.000000000 Z
11
+ date: 2026-10-19 00:00:00.000000000 Z
12
12
  dependencies: []
13
13
  description: Ruby client for Crawlora's hosted TikTok API. Covers video, user, and
14
14
  hashtag search; profiles and posts; comments; trends; Creative Center; and Top Ads
15
- data across 25 endpoints.
15
+ data across 28 endpoints.
16
16
  email:
17
17
  executables: []
18
18
  extensions: []
@@ -49,5 +49,5 @@ requirements: []
49
49
  rubygems_version: 3.4.19
50
50
  signing_key:
51
51
  specification_version: 4
52
- summary: TikTok API client for Crawlora (25 endpoints)
52
+ summary: TikTok API client for Crawlora (28 endpoints)
53
53
  test_files: []