ניטור האשטגים של TikTok בפייתון: בקשת API עובדת

צוות שיווק מבחין שסרטונים על מוצר חדש מופיעים ב-TikTok, אך קשה לבדוק ידנית כמה האשטגים מדי יום. כדי להשוות בין פרסומים ומדדים גלויים לאורך זמן, דרוש תהליך איסוף שניתן לחזור עליו, עם חותמת זמן, ארכיון של התגובות המקוריות ובדיקת שינויים.

לאב־טיפוס כזה מתאים TikTok Scraper API של jsonscraper: בעמוד המוצר מפורטים נתיבים להאשטגים, משתמשים, סרטונים וחיפוש. הצעד הראשון הוא לבדוק את הנתיב הדרוש ואת פורמט התגובה ב-Postman, ולאחר מכן להעביר את התצורה שאומתה לפייתון. כך אפשר לבנות תהליך שניתן לחזור עליו, תוך חילוץ רק של השדות שנמצאים בפועל בתגובה.

המשימה: לראות מגמות, לא סרטון פופולרי בודד

פרסום יחיד עם צפיות רבות עשוי למשוך תשומת לב, אך לתכנון קמפיין מועיל יותר להבין כמה סרטונים חדשים מתגלים בנושא וכיצד משתנים המדדים הציבוריים של פרסומים שכבר נמצאו. לדוגמה, לחנות מקוונת למוצרי ספורט חשוב להעריך את היקף הסרטונים על סוג אימון מסוים לפני הכנת קריאייטיבים הקשורים אליו.

בדיקה ידנית מקשה על ההשוואה: קבוצת התוצאות משתנה, המדדים מצטברים, ועובדים עשויים לתעד אותם בפורמטים שונים. אם שומרים תמונת מצב מכל הרצה יחד עם מועד האיסוף ונתוני ה-JSON המקוריים, הצוות מקבל היסטוריה של התצפיות שלו ויכול לעבד את הנתונים מחדש אם סכמת הניתוח משתנה.

האוטומציה מורכבת מכמה שלבים: בדיקת הנתיב והפרמטרים, בקשת נתונים לפי לוח זמנים, שמירת התגובה, אימות המבנה שלה ואז חילוץ השדות הדרושים. אפשר להשתמש בטבלה המתקבלת ליצירת תרשימים, לסיווג נושאי או לדוח.

מה מתועד בתיעוד ה-API

בעמוד TikTok Scraper API מצוינת כתובת הבסיס https://tiktok.evelode.com ומפורטים נתיבים בקטגוריית Hashtag: GET /getHashtagInfo, GET /getHashtagFeed ו-GET /getHashtagFeedByID. העמוד מציג גם דוגמת בקשה לנתיב אחר עם הפרמטר license_key, ומתאר כיצד להגדיר את המפתח באוסף Postman.

עבור GET /getHashtagFeed, מפרט הנתיבים מציין את הפרמטר החובה query (כתובת URL של האשטג או שם תג), וכן את הפרמטרים האופציונליים cursor, count, region ו-cache_timeout. תגובת הפיד צפויה להכיל את המערך tiktok.aweme_list; בין השדות המפורטים עבור פריט נמצאים aweme_id, desc, create_time, share_url, נתוני היוצר ו-statistics. שדות מסוימים עשויים להיעדר, לכן יש לבדוק את נתוני ה-JSON בפועל לפני העיבוד.

אפשר להשתמש באוסף jsonscraper ב-Postman כדי לשלוח בקשת ניסיון, להשוות את התגובה בפועל ולקבל דוגמה לבדיקה בהמשך של הקוד. לצורך אימות מועבר license_key; שמרו את המפתח במשתנה סביבה ואל תדפיסו אותו ליומנים.

קודם כול בודקים את הבקשה ב-Postman

התחילו בהאשטג אחד לבדיקה. באוסף בחרו בנתיב פיד האשטגים, הגדירו את license_key בהתאם לתיעוד והעבירו את שם התג ב-query. אם צריך, הוסיפו את count ואת קוד המדינה ב-region. שלחו את הבקשה ובדקו את קוד מצב ה-HTTP, את השדה העליון status ואת התוכן של tiktok.aweme_list.

שמרו תגובה מוצלחת כקובץ JSON לבדיקה. השתמשו בו כדי לוודא שקיימים מזהה הפרסום, התיאור, מועד הפרסום, הקישור והנתונים הסטטיסטיים. הוסיפו שדה לסכמת הניתוח רק לאחר שווידאתם שהוא מתקבל מהסוג הנדרש.

שמרו את מפתח ה-API במשתנה סביבה ולא בקובץ המקור. אם המפתח מועבר בכתובת URL, הסתירו אותו בעת רישום הבקשה ליומן כדי שהכתובת המלאה לא תופיע ביומנים.

לקוח פייתון לשליחת בקשה ולארכוב

הנתיב ושמות הפרמטרים שלהלן תואמים למפרט שפורסם: עבור האשטג משתמשים ב-query, והאימות מועבר באמצעות license_key. הדוגמה תואמת ל-Python 3.8+ ושומרת את התגובה המקורית יחד עם מטא־נתונים על ההרצה.

import json
import os
from datetime import datetime, timezone
from pathlib import Path

import requests

BASE_URL = "https://tiktok.evelode.com"
API_KEY = os.environ["JSONSCRAPER_TIKTOK_LICENSE_KEY"]


def fetch_hashtag_feed(hashtag: str) -> dict:
    params = {
        "license_key": API_KEY,
        "query": hashtag,
        "count": 20,
    }
    response = requests.get(
        f"{BASE_URL}/getHashtagFeed",
        params=params,
        timeout=45,
    )
    response.raise_for_status()
    payload = response.json()
    if payload.get("status") != "ok":
        raise RuntimeError("ה-API החזיר סטטוס שאינו ok")
    return payload


def archive_response(hashtag: str, payload: dict) -> Path:
    collected_at = datetime.now(timezone.utc).isoformat()
    safe_tag = hashtag.lstrip("#").replace("/", "_")
    output_dir = Path("data/raw") / safe_tag
    output_dir.mkdir(parents=True, exist_ok=True)

    filename = datetime.now(timezone.utc).strftime("%Y%m%dT%H%M%SZ.json")
    file_path = output_dir / filename
    file_path.write_text(
        json.dumps(
            {
                "hashtag": hashtag,
                "collected_at": collected_at,
                "response": payload,
            },
            ensure_ascii=False,
            indent=2,
        ),
        encoding="utf-8",
    )
    return file_path


if __name__ == "__main__":
    tag = "#נושאלדוגמה"
    payload = fetch_hashtag_feed(tag)
    saved_path = archive_response(tag, payload)
    print(f"הארכיון נשמר: {saved_path}")

לפני ההרצה, הגדירו את משתנה הסביבה JSONSCRAPER_TIKTOK_LICENSE_KEY. הבקשה משתמשת ב-query שאומת ומגבילה את מספר הפריטים המבוקשים באמצעות count. התוכנית בודקת את מצב ה-HTTP ואת מצב ה-JSON; הארכיון שומר את הנתונים בפועל לעיבוד בהמשך. בדקו את ההרצה עם האשטג אחד לפני הוספת לוח זמנים וניתוח נתונים.

איך להוסיף נרמול בלי הנחות שבריריות

בתיעוד מצוין שתגובת הפיד מכילה את המערך tiktok.aweme_list. לפני ההמרה, בדקו ש-tiktok הוא אובייקט ו-aweme_list היא רשימה. עבור כל פריט, חלצו רק שדות מאומתים, כגון aweme_id, desc, create_time, share_url וערכים מתוך statistics, אם הם קיימים.

הטבלה הפנימית יכולה לכלול את האשטג של הבקשה, מועד האיסוף, מזהה הסרטון והמדדים שנבחרו. עבור מדד אופציונלי או חסר, שמרו ערך ריק: מדד חסר אינו זהה למדד שנמדד כאפס. שמרו את התגובות המקוריות בנפרד, כדי שאפשר יהיה לבנות את הטבלה מחדש בלי לשלוח בקשה נוספת.

אם פורמט התגובה משתנה, בדיקת הטיפוסים צריכה לעצור עיבוד שגוי וליצור הודעת אבחון. שמרו את קובץ ה-JSON לבדיקה לצד בדיקת המנתח: הוא יסייע לוודא שגרסה חדשה של הקוד עדיין מעבדת את הסכמה המוכרת.

מדדים המבוססים על תצפיות חוזרות

אם התגובה מספקת מונים, שמרו כל תצפית עם חותמת זמן. עבור פרסום אחד, השוו את הערכים משתי הרצות וחשבו את השינוי שנצפה במהלך פרק הזמן. להשוואה השתמשו ב-aweme_id שמצוין במפרט, ובדקו שהוא קיים בכל פריט.

אפשר לספור את מספר הפרסומים שהתגלו לראשונה ביום מתוך תוצאות ההרצות שלכם. המדד הזה מתאר את זרם התוצאות שהוחזר על ידי בקשות מסוימות, עם הפרמטרים ולוח הזמנים שנקבעו. הוא מאפשר להשוות בין תמונות המצב שלכם, בתנאי ששיטת האיסוף נשארת עקבית.

דוח בסיסי יכול להציג את מספר הפרסומים החדשים שהתגלו בכל יום, את ההתפלגות של המונים הזמינים ואת השינוי בערכים של סרטונים שהתגלו שוב. הוסיפו את מועד הבקשה ואת שם קובץ המקור, כדי שהאנליסט יוכל לבדוק את מקורו של כל רישום.

לוח זמנים וטיפול בשגיאות

לאחר שבדקתם את הבקשה ואת הניתוח, הריצו את הסקריפט לפי לוח זמנים — למשל באמצעות cron, GitHub Actions או מתזמר נתונים. העבירו את רשימת ההאשטגים לקובץ תצורה נפרד, כדי להוסיף נושאים או להסירם בלי לשנות את לוגיקת הלקוח.

בהרצה אוטומטית הגדירו פסק זמן, מספר מוגבל של ניסיונות חוזרים במקרה של שגיאות רשת זמניות ורישום של קוד מצב ה-HTTP ושל משך הבקשה. אל תכתבו את המפתח ליומן. במקרה של שגיאת ניתוח, שמרו פרטי אבחון בטוחים והודיעו לעובד האחראי.

המפרט תומך בעימוד באמצעות הפרמטר cursor עבור פיד האשטגים. אם נדרש עימוד, שמרו את הסמן שהתקבל בתגובה והעבירו אותו לבקשה הבאה ללא שינוי; עבדו רק את התוצאות שהוחזרו ועקבו אחר has_more, אם הוא קיים. אם בקשות לכמה האשטגים מחזירות את אותו פרסום, בחרו מפתח למניעת כפילויות בהתאם למטרה: להתייחס לפרסום בנפרד עבור כל האשטג, או לספור רק סרטונים ייחודיים.

סיווג ואוטומציה של דוחות

לאחר קבלת שורות מאומתות, אפשר להוסיף סיווג של תיאורי סרטונים לפי נושאים מוגדרים: השדה desc מצוין בסכמת הפריט. מודל יכול לקבץ פרסומים לפי פורמט — למשל, הדרכות, סקירות או חוויות משתמש. שמרו את הטקסט המקורי, התווית, גרסת ההנחיה והתוצאה, והעבירו מקרים לא ודאיים לבדיקה אנושית.

חשבו מדדים מספריים באמצעות קוד רגיל, כדי שהרצות חוזרות יפיקו חישובים שניתן לשחזר. מסווג מועיל לעיבוד טקסט; הדוח הסופי צריך לקשר בין המסקנות לרשומות ולתאריכי התצפיות המסוימים.

בתהליך ללא קוד אפשר לחבר את אותם שלבים בכלי אוטומציה: לוח זמנים, בקשת HTTP לפי תצורה מאומתת, בדיקת התגובה, שמירת JSON, המרת שדות מאומתים והתראה על שגיאה. קודם בדקו את החוזה ב-Postman, ורק לאחר מכן העבירו אותו לפייתון, ל-n8n או ל-Make.

התוצאה הצפויה והצעד הבא

לאחר ההגדרה, יהיה לצוות ארכיון של תגובות API וטבלת תצפיות עבור ההאשטגים שנבחרו. הם יסייעו לאתר פרסומים חדשים, להשוות מדדים זמינים לאורך זמן ולבחור חומרים לניתוח מעמיק. כדי לקבל תוצאות בנות השוואה, שמרו על לוח זמנים אחיד, על פרמטרי בקשה קבועים ועל כללי נרמול עקביים.

התחילו בנתיב אחד ובתגובה אמיתית אחת: שלחו בקשה ל-/getHashtagFeed עם הפרמטר query, שמרו את ה-JSON ורק לאחר מכן הוסיפו ניתוח שדות ולוח זמנים. עמוד TikTok Scraper API מציג את כתובת הבסיס ואת מפת הנתיבים, ואילו מפרט הנתיבים כולל את שמות הפרמטרים למימוש הלקוח.