{"id":543,"date":"2025-10-26T22:43:41","date_gmt":"2025-10-26T22:43:41","guid":{"rendered":"https:\/\/ykim.synology.me\/wordpress\/?p=543"},"modified":"2025-10-26T23:14:10","modified_gmt":"2025-10-26T23:14:10","slug":"how-to-use-youtube-reporting-api","status":"publish","type":"post","link":"https:\/\/ykim.synology.me\/wordpress\/how-to-use-youtube-reporting-api-543\/","title":{"rendered":"How to use YouTube Reporting API"},"content":{"rendered":"\n

The most important thing to understand about the YouTube Reporting API is that it’s asynchronous<\/strong>.<\/p>\n\n\n\n

Unlike the Analytics API (where you ask a question and get an answer), the Reporting API works in a multi-step process:<\/p>\n\n\n\n

    \n
  1. You:<\/strong> Ask YouTube to create a “report job”<\/strong> (e.g., “Please start generating a daily report of my video stats”).<\/li>\n\n\n\n
  2. YouTube:<\/strong> Says “Okay” and, over the next 24-48 hours, starts generating these reports as CSV files<\/strong>.<\/li>\n\n\n\n
  3. You:<\/strong> Periodically check back and ask, “Are any new reports from my job ready?”<\/li>\n\n\n\n
  4. YouTube:<\/strong> “Yes, here is the download URL for yesterday’s report.”<\/li>\n\n\n\n
  5. You:<\/strong> Download the CSV file and import it into your database or spreadsheet.<\/li>\n<\/ol>\n\n\n\n

    The code is split into two main parts: (1)<\/strong> Creating the job and (2)<\/strong> Downloading the reports.<\/p>\n\n\n\n

    \n\n\n\n

    \ud83d\udc0d Python Code Examples<\/h2>\n\n\n\n

    You’ll need the Google API client library and the authentication library.<\/p>\n\n\n\n

    Bash<\/p>\n\n\n

    \npip install google-api-python-client google-auth-oauthlib requests\n\n<\/pre><\/div>\n\n\n
    You must first have an OAuth 2.0 client_secrets.json<\/code> file from your Google Cloud project with the YouTube Reporting API enabled.<\/p>\n\n\n\n
    Part 1: Creating a Reporting Job<\/h3>\n\n\n\n
    This is a one-time setup. You run this script once to tell YouTube what report you want it to start generating.<\/p>\n\n\n\n
    Python<\/p>\n\n\n
    \nimport os\nimport google_auth_oauthlib.flow\nimport googleapiclient.discovery\nimport googleapiclient.errors\n\nSCOPES = ["https.www.googleapis.com\/auth\/yt-analytics.readonly"]\nAPI_SERVICE_NAME = "youtubereporting"\nAPI_VERSION = "v1"\nCLIENT_SECRETS_FILE = "client_secrets.json" # Your downloaded credentials\n\ndef get_authenticated_service():\n    """Authenticates the user and returns the YouTube Reporting API service."""\n    flow = google_auth_oauthlib.flow.InstalledAppFlow.from_client_secrets_file(\n        CLIENT_SECRETS_FILE, SCOPES)\n    credentials = flow.run_local_server(port=0)\n    return googleapiclient.discovery.build(\n        API_SERVICE_NAME, API_VERSION, credentials=credentials)\n\ndef list_report_types(youtube_reporting):\n    """Lists available report types."""\n    print("Listing available report types...")\n    results = youtube_reporting.reportTypes().list().execute()\n    report_types = results.get("reportTypes", [])\n    \n    if not report_types:\n        print("No report types found.")\n    else:\n        for report_type in report_types:\n            print(f"  ID: {report_type['id']}, Name: {report_type['name']}")\n    return report_types\n\ndef create_reporting_job(youtube_reporting, report_type_id, job_name):\n    """Creates a new reporting job."""\n    print(f"Creating job for report type '{report_type_id}'...")\n    reporting_job = {\n        "reportTypeId": report_type_id,\n        "name": job_name\n    }\n    \n    try:\n        job = youtube_reporting.jobs().create(body=reporting_job).execute()\n        print("Job created successfully:")\n        print(f"  Job ID: {job['id']}")\n        print(f"  Report Type ID: {job['reportTypeId']}")\n        print(f"  Name: {job['name']}")\n        print(f"  Create Time: {job['createTime']}")\n    except googleapiclient.errors.HttpError as e:\n        print(f"An HTTP error {e.resp.status} occurred: {e.content}")\n\nif __name__ == "__main__":\n    # Remove OAUTHLIB_INSECURE_TRANSPORT warning for local testing\n    os.environ["OAUTHLIB_INSECURE_TRANSPORT"] = "1"\n    \n    service = get_authenticated_service()\n    \n    # First, see what reports are available\n    list_report_types(service)\n    \n    # --- Example: Create a "Basic Channel Video Stats" job ---\n    # You would get this ID from the list_report_types() output.\n    # 'channel_basic_a2' is a common one for daily video stats.\n    REPORT_ID_TO_CREATE = "channel_basic_a2"\n    JOB_NAME = "Daily Video Stats Job"\n    \n    create_reporting_job(service, REPORT_ID_TO_CREATE, JOB_NAME)\n\n<\/pre><\/div>\n\n\n
    Part 2: Downloading an Available Report<\/h3>\n\n\n\n
    You would run this script daily (or hourly) to check for and download new report files.<\/p>\n\n\n\n
    Python<\/p>\n\n\n
    \nimport os\nimport requests\nimport google_auth_oauthlib.flow\nimport googleapiclient.discovery\nfrom io import FileIO\n\n# (Use the same get_authenticated_service() function from Part 1)\n# ... (get_authenticated_service code here) ...\n\ndef list_jobs(youtube_reporting):\n    """Lists all created reporting jobs."""\n    print("Listing all reporting jobs...")\n    results = youtube_reporting.jobs().list().execute()\n    jobs = results.get("jobs", [])\n    \n    if not jobs:\n        print("No jobs found.")\n    else:\n        for job in jobs:\n            print(f"  Job ID: {job['id']}, Name: {job['name']}, Report Type: {job['reportTypeId']}")\n    return jobs\n\ndef get_latest_report_url(youtube_reporting, job_id):\n    """Gets the download URL for the most recent report from a job."""\n    print(f"Finding reports for job ID: {job_id}...")\n    results = youtube_reporting.jobs().reports().list(jobId=job_id).execute()\n    reports = results.get("reports", [])\n    \n    if not reports:\n        print("No reports found for this job yet. (It can take 24-48 hours to generate the first one)")\n        return None\n        \n    # Reports are listed newest-first, so index 0 is the latest\n    latest_report = reports[0]\n    print(f"Found report: {latest_report['id']}")\n    print(f"  Covers period: {latest_report['startTime']} to {latest_report['endTime']}")\n    print(f"  Download URL: {latest_report['downloadUrl']}")\n    return latest_report['downloadUrl']\n\ndef download_report_file(report_url, local_file_name):\n    """Downloads the report file from the given URL."""\n    print(f"Downloading report to '{local_file_name}'...")\n    \n    # Note: The download URL requires the same OAuth credentials\n    # For simplicity, this example uses 'requests', but a real app\n    # would add the auth headers from the 'credentials' object.\n    # A simple GET request often works for testing.\n    response = requests.get(report_url)\n    \n    if response.status_code == 200:\n        with open(local_file_name, "wb") as f:\n            f.write(response.content)\n        print("Download complete.")\n    else:\n        print(f"Download failed with status code: {response.status_code}")\n        print(response.text)\n\nif __name__ == "__main__":\n    os.environ["OAUTHLIB_INSECURE_TRANSPORT"] = "1"\n    service = get_authenticated_service()\n    \n    # First, list your jobs to find the ID you want\n    jobs = list_jobs(service)\n    \n    if jobs:\n        # Use the ID of the job you created in Part 1\n        JOB_ID_TO_DOWNLOAD = jobs[0]['id'] # Just using the first job for this example\n        \n        report_url = get_latest_report_url(service, JOB_ID_TO_DOWNLOAD)\n        \n        if report_url:\n            download_report_file(report_url, "my_youtube_report.csv")\n\n<\/pre><\/div>\n\n\n
    \n\n\n\n
    \ud83d\udcca Typical Output (The CSV File)<\/h2>\n\n\n\n
    The API calls themselves just return JSON about the jobs<\/em> and reports<\/em> (like the text you see in the console output). The real output<\/strong> is the .csv<\/code> file you download.<\/p>\n\n\n\n
    Here is a sample of what the channel_basic_a2<\/code><\/strong> report (a common one) looks like:<\/p>\n\n\n\n
    \ucf54\ub4dc \uc2a4\ub2c8\ud3ab<\/p>\n\n\n
    \ndate,channel_id,video_id,views,red_views,comments,likes,dislikes,shares,estimated_minutes_watched,average_view_duration,average_view_percentage,subscribers_gained,subscribers_lost,videos_added_to_playlists,videos_removed_from_playlists,annotation_click_through_rate,annotation_close_rate\n2025-10-24,UCxxxxxxxxxxxxxxxxxA,VIDEO_ID_ONE,1025,150,5,25,1,3,2840,166,45.2,12,1,3,0,0,0\n2025-10-24,UCxxxxxxxxxxxxxxxxxA,VIDEO_ID_TWO,5034,780,42,150,8,15,19870,236,52.1,45,3,10,2,0,0\n2025-10-24,UCxxxxxxxxxxxxxxxxxA,VIDEO_ID_THREE,890,40,1,12,0,1,1500,101,30.9,3,0,0,1,0,0\n\n<\/pre><\/div>\n\n\n
    Key takeaways from the output:<\/strong><\/p>\n\n\n\n