### Start Media Download Example

Source: https://github.com/paularossi/addownloader/blob/main/docs/html/_sources/media_download.rst.txt

Initiates the media download process by calling the start_media_download function with project name, number of ads, and ad data.

```python
>>> start_media_download(project_name = "test1", nr_ads = 20, data = data)
```

--------------------------------

### Install from Source

Source: https://github.com/paularossi/addownloader/blob/main/README.md

Install AdDownloader from a source distribution file (.tar.gz). Ensure the virtual environment is activated.

```bash
python -m pip install "dist/AdDownloader-0.2.10.tar.gz"
```

--------------------------------

### Install from Built Distribution

Source: https://github.com/paularossi/addownloader/blob/main/README.md

Install AdDownloader from a built wheel distribution file (.whl). Ensure the virtual environment is activated.

```bash
python -m pip install "dist/AdDownloader-0.2.10-py3-none-any.whl"
```

--------------------------------

### Navigate to Project Directory

Source: https://github.com/paularossi/addownloader/blob/main/README.md

Change the current directory to the AdDownloader project folder. This is a prerequisite for installation.

```bash
cd [path-to-your-project]/AdDownloader
```

--------------------------------

### Install from Pip

Source: https://github.com/paularossi/addownloader/blob/main/README.md

Install AdDownloader as a Python package directly from pip. Ensure the virtual environment is activated.

```bash
python -m pip install AdDownloader
```

--------------------------------

### Installing AdDownloader from TestPyPi

Source: https://github.com/paularossi/addownloader/blob/main/docs/html/_modules/AdDownloader/cli.html

Instructions for installing a test version of the AdDownloader package from TestPyPi. This is useful for testing new releases before they are published to the main PyPI repository.

```bash
# to install the test version, inside the directory with venv run: 'python -m pip install --index-url https://test.pypi.org/simple/ AdDownloader'
```

--------------------------------

### Start Ad Data Download

Source: https://github.com/paularossi/addownloader/blob/main/docs/html/_sources/adlib_api.rst.txt

Initiate the download of ad data. The method returns a pandas DataFrame, and this example shows how to print the head of the downloaded data.

```python
data = ads_api.start_download()
print(data.head(1))
```

--------------------------------

### Start Media Download Process

Source: https://github.com/paularossi/addownloader/blob/main/docs/html/_modules/AdDownloader/media_download.html

Initiates the media download process for a specified project and number of ads. It creates necessary output folders if they don't exist.

```python
from selenium import webdriver
from selenium.webdriver.common.by import By
from selenium.webdriver.support.ui import WebDriverWait
from selenium.webdriver.support import expected_conditions as EC
from selenium.common.exceptions import NoSuchElementException
import requests
import os

def start_media_download(project_name, nr_ads, data=[]):
    """
    Start media content download for a given project and desired number of ads. 
    The ads media are saved in the output folder with the project_name.

    :param project_name: A running Chrome webdriver.
    :type project_name: str
    :param nr_ads: The desired number of ads for which media content should be downloaded.
    :type nr_ads: int
    :param data: A dataframe containing a ad_snapshot_url column.
    :type data: pd.DataFrame
    """

    # check if the nr of ads to download is within the length of the data
    if nr_ads > len(data):
        nr_ads = len(data)
    print(f"Downloading media content for project {project_name}.")
    nr_ads_processed = 0

    # initialize folders for the images and videos of current category
    folder_path_img = f"output\\{project_name}\\ads_images"
    folder_path_vid = f"output\\{project_name}\\ads_videos"

    # check if the folders exist
    if not os.path.exists(folder_path_img):
        os.makedirs(folder_path_img)

    if not os.path.exists(folder_path_vid):
        os.makedirs(folder_path_vid)

```

--------------------------------

### Download Media Example

Source: https://github.com/paularossi/addownloader/blob/main/docs/html/_sources/media_download.rst.txt

Demonstrates how to download media content by first navigating to an ad snapshot URL, locating the media element, extracting its URL and type, and then calling the download_media function.

```python
>>> driver.get(data['ad_snapshot_url'][0])
>>> img_element = driver.find_element(By.XPATH, img_xpath)
>>> media_url = img_element.get_attribute('src')
>>> media_type = 'image'
>>> download_media(media_url, media_type, str(data['id'][i]), folder_path_img)
```

--------------------------------

### Accept Cookies Example

Source: https://github.com/paularossi/addownloader/blob/main/docs/html/_sources/media_download.rst.txt

Shows how to initialize a Chrome WebDriver, navigate to an ad snapshot URL, and then use the accept_cookies function to handle cookies.

```python
>>> driver = webdriver.Chrome()
>>> driver.get(data['ad_snapshot_url'][0]) # start from here to accept cookies
>>> accept_cookies(driver)
```

--------------------------------

### Building and Distributing AdDownloader

Source: https://github.com/paularossi/addownloader/blob/main/docs/html/_modules/AdDownloader/cli.html

Commands for building new distributions of the AdDownloader package and uploading them to TestPyPi. This process is necessary after making changes to the source code or setup configuration.

```bash
# to build new distributions (new versions), in the cmd inside the venv run 'python -m build'
# then, to upload the dist archives to TestPyPi, run 'python -m twine upload --repository testpypi dist/*'
```

--------------------------------

### Start Ad Download and Display Head

Source: https://github.com/paularossi/addownloader/blob/main/docs/html/adlib_api.html

Initiates a download of ad data and displays the first row of the resulting DataFrame. Ensure the AdLibAPI is initialized before use.

```python
>>> data = ads_api.start_download()
>>> print(data.head(1))
```

--------------------------------

### Run Analytics Dashboard from IDE

Source: https://github.com/paularossi/addownloader/blob/main/README.md

Start the AdDownloader Analytics Dashboard programmatically from within an IDE. This function may take some time to load.

```python
from AdDownloader.start_app import start_gui # takes some time to load...
start_gui()
```

--------------------------------

### Run AdDownloader Analytics Dashboard

Source: https://github.com/paularossi/addownloader/blob/main/docs/source/index.md

Starts the AdDownloader graphical user interface, which launches an HTML page for data exploration and statistics. This function may take some time to load.

```python
from AdDownloader.start_app import start_gui
start_gui()
```

--------------------------------

### Download Ad Data and Media

Source: https://github.com/paularossi/addownloader/blob/main/docs/source/index.md

This snippet shows how to initialize the AdLibAPI, set download parameters, start the ad data download, and then download the associated media. It also demonstrates downloading media from a previously downloaded dataset.

```python
from AdDownloader import adlib_api
from AdDownloader.media_download import start_media_download
import pandas as pd

access_token = input() # your fb-access-token-here
# initialize the AdLibAPI object
ads_api = adlib_api.AdLibAPI(access_token, project_name = "test1")

# either search_terms OR search_pages_ids
ads_api.add_parameters(ad_reached_countries = 'BE', ad_delivery_date_min = "2023-09-01", ad_delivery_date_max = "2023-09-02", search_terms = "pizza")

# check the parameters
ads_api.get_parameters()

# start the ad data download
data = ads_api.start_download()

# if you want to download media right away
start_media_download(project_name = "test1", nr_ads = 20, data = data)

# if you want to download media from an earlier project
data_path = 'path/to/your/data.xlsx'
new_data = pd.read_excel(data_path)

start_media_download(project_name = "test2", nr_ads = 20, data = new_data)

# you can find all the output in the 'output/your-project-name' folder
```

--------------------------------

### Start Ad Download Process

Source: https://github.com/paularossi/addownloader/blob/main/docs/html/_modules/AdDownloader/adlib_api.html

Initiates the download from the Meta Ad Library API using specified parameters. Handles pagination for page ID searches and processes the downloaded data into a DataFrame.

```python
def start_download(self, params=None):
        """
        Start the download process from the Meta Ad Library API based on the provided parameters.

        :param params: The parameters for the API request. Default is None, parameters are retrieved from the created AdLibApi object.
        :type params: dict
        :returns: A dataframe containing the downloaded and processed ad data from the Meta Online Ad Library.
        :rtype: pd.Dataframe
        """
        if params is None:
            params = self.request_parameters

        if params["search_terms"] is not None:
            self.fetch_data(url=self.base_url, params=params, page_number=1)
        
        if params["search_page_ids"] is not None:
            search_page_ids_list = params["search_page_ids"]
            for i in range(0, len(search_page_ids_list), 10):
                end_index = min(i + 9, len(search_page_ids_list) - 1)
                print(f"Fetching data starting for indexes [{i},{end_index}]")
                params["search_page_ids"] = str(search_page_ids_list[i:end_index])

                # call the function with the initial API endpoint and parameters
                self.fetch_data(self.base_url, params, page_ids=f"[{i},{end_index}]", page_number=1)
        
        print("Done downloading json files for the given parameters.")
        print("Data processing will start now.")

        # process into excel files:
        try:
            final_data = transform_data(self.project_name, country=params["ad_reached_countries"])
            total_ads = len(final_data)
            print(f"Done processing and saving ads data for {total_ads} ads for project {self.project_name}.")
            return(final_data)

        except Exception:
            print("No data was downloaded. Please try a new request.")

```

--------------------------------

### Start Ad Download

Source: https://github.com/paularossi/addownloader/blob/main/README.md

Retrieve and download ad data based on the previously set parameters. This function returns the data needed for media retrieval.

```python
ads_api.get_parameters()
data = ads_api.start_download()
```

--------------------------------

### Start Ad Download

Source: https://github.com/paularossi/addownloader/blob/main/docs/source/adlib_api.md

Initiates the download of ad data from the Meta Ad Library API. Call this method to retrieve ad information based on the AdLibApi object's configured parameters.

```python
>>> data = ads_api.start_download()
>>> print(data.head(1))
      id ad_delivery_start_time ad_delivery_stop_time  ... unknown_45-54 unknown_55-64 unknown_65+
0  11111             2023-06-30            2024-01-09  ...          21.0           5.0        11.0
```

--------------------------------

### Start Batch Media Download

Source: https://github.com/paularossi/addownloader/blob/main/docs/html/media_download.html

Initiate the download of media content for a specified number of ads within a project. The downloaded media will be saved in an output folder named after the project. Requires a pandas DataFrame with an 'ad_snapshot_url' column.

```python
start_media_download(project_name = "test1", nr_ads = 20, data = data)
```

--------------------------------

### Interactive Introductory Messages and Task Selection

Source: https://github.com/paularossi/addownloader/blob/main/docs/html/_modules/AdDownloader/cli.html

This function displays welcome messages, prompts the user to select a task, and gathers necessary information like access tokens or project names based on the chosen task. It uses a list of questions to guide the user through the process.

```python
def intro_messages():
    """
    Display introductory messages and gather user input and Meta developer access token for selected task.
    After selecting the task, the respective function will be run.
    """
    questions = [
        {
            'type': 'list',
            'name': 'task',
            'message': 'Welcome to the AdDownloader! Select the task you want to perform: ',
            'choices': [
                        {
                            'name': 'A - download ads data only',
                        },
                        {
                            'name': 'B - download ads media content only',
                        },
                        {
                            'name': 'C - download both ads data and media content',
                        },
            ],
        },
        {
            'type': 'password',
            'name': 'access_token',
            'message': 'Please provide your access token',
            'when': lambda answers: answers['task'] == 'A - download ads data only' or 
                                    answers['task'] == 'C - download both ads data and media content'
        },
        {
            'type': 'confirm',
            'name': 'start',
            'message': 'Are you sure you want to proceed?',
        }
    ]

    answers = prompt(questions, style=default_style)

    rprint(f"[green bold]You have chosen task {answers['task']}.[green bold]")

    if answers['task'] == 'A - download ads data only':
        rprint("[yellow]Please enter a name for your project. All created folders will use this name:[yellow]")
        project_name = input()
        run_task_A(project_name, answers)
    
    if answers['task'] == 'B - download ads media content only':
        rprint("[yellow]Please enter the name of the project you have ads data for.\n The data needs to be in the output\project_name\\ads_data folder.[yellow]")
        project_name = input()
        rprint("[yellow]Please enter the name of the excel file containing ads data.\n The data needs to be in the output\project_name\\ads_data folder.[yellow]")
        file_name = input()
        run_task_B(project_name, file_name)

    if answers['task'] == 'C - download both ads data and media content':
        rprint("[yellow]Please enter a name for your project. All created folders will use this name:[yellow]")
        project_name = input()
        run_task_A(project_name, answers)
        run_task_B(project_name)
        

    rprint("[yellow]=============================================[yello]")
    rprint("Finished.")
```

--------------------------------

### Start Political Ad Download and Media Retrieval

Source: https://github.com/paularossi/addownloader/blob/main/README.md

Download political ad data and then retrieve their associated media content. The output is stored in the 'output/<project_name>' folder.

```python
plt_ads_api.get_parameters()
plt_data = plt_ads_api.start_download()
start_media_download(project_name = "test2", nr_ads = 20, data = plt_data)
```

--------------------------------

### Analyze Text Data Manually with AdDownloader

Source: https://github.com/paularossi/addownloader/blob/main/docs/source/index.md

Loads ad data from an Excel file, generates various exploratory data analysis graphs, performs text analysis on ad captions (keyword frequency, sentiment, topic modeling), and displays a word cloud. Ensure the data path is correct and necessary libraries like matplotlib are installed.

```python
from AdDownloader.analysis import *
import matplotlib.pyplot as plt
data_path = "output/test1/ads_data/test1_processed_data.xlsx"
data = load_data(data_path)
data.head(20)

# create graphs with EDA
fig1, fig2, fig3, fig4, fig5, fig6, fig7, fig8, fig9, fig10 = get_graphs(data)
fig1.show() # will open a webpage with the graph, which can also be saved locally

# perform text analysis of the ad captions
tokens, freq_dist, word_cl, textblb_sent, nltk_sent = start_text_analysis(data['ad_creative_bodies'])
print(f"Most common 10 keywords: {freq_dist.most_common(10)}")

# show the word cloud
plt.imshow(word_cl, interpolation='bilinear')
plt.axis("off")
plt.show()

# check the sentiment
textblb_sent.head(20) # or textblb_sent

# get the topics
lda_model, coherence, topics_df = get_topics(tokens, num_topics = 5)

# print the top 5 words for each topic and the coherence score
for idx, topic in lda_model.print_topics(num_words=5):
   print("Topic: {} \nWords: {}".format(idx + 1, topic))

print('Coherence Score:', coherence)
```

--------------------------------

### Download Media from Ads

Source: https://github.com/paularossi/addownloader/blob/main/docs/html/_modules/AdDownloader/media_download.html

Iterates through ad data, downloads images or videos using Selenium WebDriver, and handles cases with single media elements or multiple images per ad. Requires WebDriver setup and a function to accept cookies.

```python
if not os.path.exists(folder_path_vid):
    os.makedirs(folder_path_vid)

# define some constants first
img_xpath = '//*[@id="content"]/div/div/div/div/div/div/div[2]/a/div[1]/img'
video_xpath = '//*[@id="content"]/div/div/div/div/div/div/div[2]/div[2]/video'
#multpl_img_xpath = '//*[@id="content"]/div/div/div/div/div/div/div[3]/div/div/div/div[{}]/div/div/a/div[1]/img'
# //*[@id="content"]/div/div/div/div/div/div/div[2]/div[2]/img
multpl_img_xpath = '//*[@id="content"]/div/div/div/div/div/div/div[3]/div/div/div/div[{}]/div/div/div/img'

# start the downloads here, accept cookies
driver = webdriver.Chrome()
# sample the nr_ads
data = data.sample(nr_ads)
data = data.reset_index(drop=True)

driver.get(data['ad_snapshot_url'][0]) # start from here to accept cookies
accept_cookies(driver)

# for each ad in the dataset download the media
for i in range(0, nr_ads): #TODO: randomize the ads to download
    # get the target ad
    driver.get(data['ad_snapshot_url'][i])

    try: # first try to get the img
        img_element = driver.find_element(By.XPATH, img_xpath)
        # if it's found, get its url and download it
        media_url = img_element.get_attribute('src')
        media_type = 'image'
        download_media(media_url, media_type, str(data['id'][i]), folder_path_img)
        nr_ads_processed += 1

    except NoSuchElementException:
        try: # otherwise try to find the video
            video_element = driver.find_element(By.XPATH, video_xpath)
            # if it's found, get its url and download it
            media_url = video_element.get_attribute('src')
            media_type = 'video'
            download_media(media_url, media_type, str(data['id'][i]), folder_path_vid)
            nr_ads_processed += 1
        
        except NoSuchElementException:
            # means there must be more than 1 image:
            # determine the number of images on the page
            image_count = len(driver.find_elements(By.XPATH, multpl_img_xpath.format('*')))
            if image_count == 0:
                print(f"No media were downloaded for ad {data['id'][i]}.")
                continue
            print(f'{image_count} media content found. Trying to retrieve all of them.')
            
            # iterate over the images and download each one
            for img_index in range(1, image_count + 1):
                multpl_img_element = driver.find_element(By.XPATH, multpl_img_xpath.format(img_index))
                media_url = multpl_img_element.get_attribute('src')
                media_type = 'image'
                download_media(media_url, media_type, f"{str(data['id'][i])}_{img_index}", folder_path_img)
            nr_ads_processed += 1

print(f'Finished saving media content for {nr_ads_processed} ads for project {project_name}.')

# close the driver once it's done downloading
driver.quit()
```

--------------------------------

### Running the AdDownloader Tool

Source: https://github.com/paularossi/addownloader/blob/main/docs/html/_modules/AdDownloader/cli.html

Instructions on how to set up and run the AdDownloader tool from the command line. This includes creating and activating a virtual environment, and running the main module.

```bash
# to run the tool: open a cmd and go to the directory of the project 'cd My Documents\AdDownloader'
# inside your directory, create a virtual environment with 'python -m venv venv'
# activate the virtual environment with 'venv\Scripts\activate.bat'
# then start the app with 'python -m AdDownloader.cli'
```

--------------------------------

### Initialize AdDownloader API and Add Parameters

Source: https://github.com/paularossi/addownloader/blob/main/README.md

Instantiate the AdLibAPI with an access token and project name, then add search parameters for downloading ads. Ensure the access token is provided.

```python
from AdDownloader import adlib_api
from AdDownloader.media_download import start_media_download

access_token = input() # the best way to upload your token
ads_api = adlib_api.AdLibAPI(access_token, project_name = "test1")
ads_api.add_parameters(ad_reached_countries = 'BE', ad_delivery_date_min = "2023-12-01", ad_delivery_date_max = "2023-12-31", 
                       search_terms = "McDonald's")
```

--------------------------------

### Get API Request Parameters

Source: https://github.com/paularossi/addownloader/blob/main/docs/html/_modules/AdDownloader/adlib_api.html

Retrieves the currently set parameters for the API request. This is useful for inspection or debugging.

```python
def get_parameters(self):
        """
        Get the parameters used for the API request.

        :returns: A dictionary containing the parameters for the API request.
        :rtype: dict
        """

        return(self.request_parameters)

```

--------------------------------

### AdDownloader.cli.intro_messages

Source: https://github.com/paularossi/addownloader/blob/main/docs/html/cli.html

Displays introductory messages and gathers user input, including the Meta developer access token, for selected tasks. After task selection, the respective function is executed.

```APIDOC
## AdDownloader.cli.intro_messages

### Description
Display introductory messages and gather user input and Meta developer access token for selected task. After selecting the task, the respective function will be run.

### Method
Not specified (CLI function)

### Endpoint
Not specified (CLI function)
```

--------------------------------

### Get Default API Fields

Source: https://github.com/paularossi/addownloader/blob/main/docs/html/_modules/AdDownloader/adlib_api.html

Retrieves the default fields that will be requested from the API if no specific fields are provided during parameter setting.

```python
def get_fields(self):
        """
        Get the default fields for the API request.
        
```

--------------------------------

### Get Ad API Fields

Source: https://github.com/paularossi/addownloader/blob/main/docs/html/_modules/AdDownloader/adlib_api.html

Retrieves a comma-separated string of fields for an API request. This is useful for fetching specific ad details.

```python
return("id, ad_delivery_start_time, ad_delivery_stop_time, ad_creative_bodies, ad_creative_link_captions, ad_creative_link_descriptions, ad_creative_link_titles, ad_snapshot_url, page_id, page_name, target_ages, target_gender, target_locations, eu_total_reach, age_country_gender_reach_breakdown")
```

--------------------------------

### Run AdDownloader CLI from Command Line

Source: https://github.com/paularossi/addownloader/blob/main/README.md

Launch the AdDownloader Command Line Interface (CLI) tool from the command line. Ensure the virtual environment is activated.

```bash
python -m AdDownloader.cli
```

--------------------------------

### AdDownloader CLI Entry Point

Source: https://github.com/paularossi/addownloader/blob/main/docs/html/_modules/AdDownloader/cli.html

This is the main entry point for the AdDownloader CLI application. It initializes the Typer app and runs it when the script is executed directly.

```python
app = typer.Typer() # create the app

@app.command("run-analysis")
def run_analysis():
    """
    Main function to run the AdDownloader tool until the user stops the analysis.
    """
    #TODO: add logging tracking?
    while True:
        intro_messages()

        # Prompt to ask if the user wants to perform another analysis
        rerun = typer.confirm("Do you want to perform a new analysis?")
        if not rerun:
            rprint("[yellow]=============================================[yello]")
            rprint("[yellow]Analysis completed. Thank you for using AdDownloader! [yello]")
            break

# need this to run the app
if __name__ == "__main__":
    app()
```

--------------------------------

### Get AdLib API Parameters

Source: https://github.com/paularossi/addownloader/blob/main/docs/html/adlib_api.html

Retrieves the current parameters configured for the AdLib API request. This is useful for inspecting or modifying request settings.

```python
>>> ads_api.get_parameters()
{'fields': 'id, ad_delivery_start_time, ad_delivery_stop_time, ad_creative_bodies, ad_creative_link_captions, ad_creative_link_descriptions, ad_creative_link_titles, ad_snapshot_url, page_id, page_name, target_ages, target_gender, target_locations, eu_total_reach, age_country_gender_reach_breakdown', 'ad_reached_countries': 'BE', 'search_page_ids': None, 'search_terms': 'pizza', 'ad_delivery_date_min': '2023-09-01', 'ad_delivery_date_max': '2023-09-02', 'limit': '300', 'access_token': 'XX'}
```

--------------------------------

### Get Current API Parameters

Source: https://github.com/paularossi/addownloader/blob/main/docs/html/_sources/adlib_api.rst.txt

Retrieve the current set of parameters configured for the AdLibAPI instance. These parameters are used in subsequent API calls.

```python
ads_api.get_parameters()
```

--------------------------------

### Initialize AdDownloader for Political Ads

Source: https://github.com/paularossi/addownloader/blob/main/README.md

Instantiate the AdLibAPI specifically for downloading POLITICAL_AND_ISSUE_ADS. Parameters like country, date range, and ad type are specified.

```python
from AdDownloader import adlib_api
from AdDownloader.media_download import start_media_download

plt_ads_api = adlib_api.AdLibAPI(access_token, project_name = "test2")
plt_ads_api.add_parameters(ad_reached_countries = 'US', ad_delivery_date_min = "2020-10-01", ad_delivery_date_max = "2020-10-03", 
                           ad_type = "POLITICAL_AND_ISSUE_ADS", search_page_ids = "us_parties.xlsx")
```

--------------------------------

### AdLibAPI.start_download()

Source: https://github.com/paularossi/addownloader/blob/main/docs/html/adlib_api.html

Initiates the download process from the Meta Ad Library API using the configured parameters.

```APIDOC
## AdLibAPI.start_download()

### Description
Start the download process from the Meta Ad Library API based on the provided parameters.

### Parameters
* **params** (dict) - Optional - The parameters for the API request. Default is None, parameters are retrieved from the created AdLibApi object.

### Returns
A dataframe containing the downloaded and processed ad data from the Meta Online Ad Library.

### Return type
pd.Dataframe

### Example
```python
# Example usage would follow, but is not provided in the source text.
```
```

--------------------------------

### Get AdLib API Fields

Source: https://github.com/paularossi/addownloader/blob/main/docs/html/adlib_api.html

Retrieves the default set of fields used in AdLib API requests. This string defines the data points that can be requested.

```python
>>> ads_api.get_fields()
'id, ad_delivery_start_time, ad_delivery_stop_time, ad_creative_bodies, ad_creative_link_captions, ad_creative_link_descriptions, ad_creative_link_titles, ad_snapshot_url,
page_id, page_name, target_ages, target_gender, target_locations, eu_total_reach, age_country_gender_reach_breakdown'
```

--------------------------------

### Run Analytics Dashboard from Command Line

Source: https://github.com/paularossi/addownloader/blob/main/README.md

Launch the AdDownloader Analytics Dashboard from the command line. Ensure the virtual environment is activated.

```bash
python -m AdDownloader.app
```

--------------------------------

### start_media_download

Source: https://github.com/paularossi/addownloader/blob/main/docs/html/_modules/AdDownloader/media_download.html

Initiates the media content download process for a specified project. It sets up output folders for images and videos and processes a given number of ads from the provided data.

```APIDOC
## start_media_download

### Description
Starts the media content download for a given project, specifying the number of ads to process. It creates necessary output directories and prepares for downloading media.

### Parameters
#### Path Parameters
- **project_name** (str) - Required - The name of the project for which media content will be downloaded. This name is used to create the output directory structure.
- **nr_ads** (int) - Required - The desired number of ads for which media content should be downloaded. If this number exceeds the available data, it will be capped at the data length.
- **data** (pd.DataFrame) - Required - A pandas DataFrame containing ad data, expected to have at least an 'ad_snapshot_url' column.

### Request Example
```python
# Example usage (assuming 'df' is a pandas DataFrame with ad data):
# start_media_download('MyProject', 50, df)
```

### Response
This function does not return a value but prints status messages to the console and creates directories.

#### Success Response (Console Output)
- Prints 'Downloading media content for project [project_name].' upon initiation.

#### Side Effects
- Creates output directories: `output/[project_name]/ads_images` and `output/[project_name]/ads_videos` if they do not already exist.
```

--------------------------------

### Get Available API Fields

Source: https://github.com/paularossi/addownloader/blob/main/docs/html/_sources/adlib_api.rst.txt

Retrieve a string listing all available fields that can be requested from the Ad Library API. This is useful for understanding what data points are accessible.

```python
ads_api.get_fields()
```

--------------------------------

### start_media_download Function

Source: https://github.com/paularossi/addownloader/blob/main/docs/html/media_download.html

Initiates the download of media content for a specified project and number of ads, saving them to an output folder.

```APIDOC
## AdDownloader.media_download.start_media_download

### Description
Start media content download for a given project and desired number of ads. The ads media are saved in the output folder with the project_name.

### Method
Not applicable (Python function)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
* **project_name** (_str_) – A running Chrome webdriver.
* **nr_ads** (_int_) – The desired number of ads for which media content should be downloaded.
* **data** (_pd.DataFrame_) – A dataframe containing a ad_snapshot_url column.

### Request Example
```python
start_media_download(project_name = "test1", nr_ads = 20, data = data)
```

### Response
#### Success Response
None explicitly documented.

#### Response Example
None explicitly documented.
```

--------------------------------

### AdLibAPI.start_download

Source: https://github.com/paularossi/addownloader/blob/main/docs/html/_sources/adlib_api.rst.txt

Initiates the download of ad data.

```APIDOC
## AdLibAPI.start_download

### Description
Initiates the download of ad data.

### Method
start_download

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```python
>>> data = ads_api.start_download()
>>> print(data.head(1))
      id ad_delivery_start_time ad_delivery_stop_time  ... unknown_45-54 unknown_55-64 unknown_65+
0  11111             2023-06-30            2024-01-09  ...          21.0           5.0        11.0
```

### Response
None
```

--------------------------------

### AdDownloader.cli.run_task_A

Source: https://github.com/paularossi/addownloader/blob/main/docs/html/cli.html

Executes task A, which involves downloading ad data from the Meta Online Ad Library based on user-specified parameters.

```APIDOC
## AdDownloader.cli.run_task_A

### Description
Run task A: Download ads data from the Meta Online Ad Library based on user-provided parameters.

### Method
Not specified (CLI function)

### Endpoint
Not specified (CLI function)

### Parameters
#### Path Parameters
* **project_name** (str) - Required - The name of the current project.
* **answers** (dict) - Required - User’s answers from the initial questions for tasks A/C regarding desired parameters.
```

--------------------------------

### AdLibAPI.__init__

Source: https://github.com/paularossi/addownloader/blob/main/docs/html/_modules/AdDownloader/adlib_api.html

Initializes the AdLibAPI object with access token and API version. Sets up the base URL and retrieves default fields.

```APIDOC
## AdLibAPI.__init__

### Description
Initializes the AdLibAPI object with the provided access token and API version. It sets up the base URL for the Meta Ad Library API and retrieves the default fields required for API requests.

### Method
__init__

### Parameters
- **access_token** (str) - Required - The access token for authentication.
- **version** (str) - Optional - The version of the Meta Ad Library API. Defaults to "v18.0".
```

--------------------------------

### Get Default Fields for Ad Type

Source: https://github.com/paularossi/addownloader/blob/main/docs/source/adlib_api.md

Retrieves the default fields for an API request, which vary depending on whether you are fetching 'ALL' ads or 'Political' ads. Visit the Facebook Ads Library API documentation for a complete list of available fields.

```pycon
>>> ads_api.get_fields(ad_type = "ALL")
'id, ad_delivery_start_time, ad_delivery_stop_time, ad_creative_bodies, ad_creative_link_captions, ad_creative_link_descriptions, ad_creative_link_titles, ad_snapshot_url,
page_id, page_name, target_ages, target_gender, target_locations, eu_total_reach, age_country_gender_reach_breakdown'
```

--------------------------------

### Manual Ad Data and Media Download with AdLibAPI

Source: https://github.com/paularossi/addownloader/blob/main/docs/html/_sources/homepage.rst.txt

This snippet demonstrates how to manually download ad data and media content using the AdLibAPI class and the start_media_download function. It requires a Meta developer access token and allows specifying search parameters.

```python
from AdDownloader import adlib_api
from AdDownloader.media_download import start_media_download
from AdDownloader.cli import run_analysis
import pandas as pd

access_token = input() # your fb-access-token-here
# initialize the AdLibAPI object
ads_api = adlib_api.AdLibAPI(access_token)

# either search_terms OR search_pages_ids
ads_api.add_parameters(countries = 'BE', start_date = "2023-09-01", end_date = "2023-09-02", search_terms = "pizza", project_name = "test1")

# check the parameters
ads_api.get_parameters()

# start the ad data download
data = ads_api.start_download()

# if you want to download media right away
start_media_download(project_name = "test1", nr_ads = 20, data = data)

# if you want to download media from an earlier project
data_path = 'path/to/your/data.xlsx'
new_data = pd.read_excel(data_path)

start_media_download(project_name = "test2", nr_ads = 20, data = new_data)

# you can find all the output in the 'output/your-project-name' folder
```

--------------------------------

### AdLibAPI.__init__

Source: https://github.com/paularossi/addownloader/blob/main/docs/source/adlib_api.md

Initializes the AdLibAPI object. Requires a Meta developer access token and optionally accepts API version and project name.

```APIDOC
## AdLibAPI.__init__

### Description
Initializes the AdLibAPI object by providing a valid Meta developer token and a project name.

### Method
__init__

### Parameters
#### Parameters
- **access_token** (str) - Required - The access token for authentication.
- **version** (str) - Optional - The version of the Meta Ad Library API. Default is “v18.0”.
- **project_name** (str) - Optional - The name of the project. Default is the current date and time.

### Request Example
```python
>>> from AdDownloader import adlib_api
>>> access_token = input() # your fb-access-token-here
>>> ads_api = adlib_api.AdLibAPI(access_token, project_name = "test1")
```
```

--------------------------------

### Automated Ad Download using CLI

Source: https://github.com/paularossi/addownloader/blob/main/docs/html/_sources/homepage.rst.txt

This snippet shows how to run the AdDownloader as an automated command-line interface. This is a simple and intuitive way to download ad data and media content without writing Python code.

```python
from AdDownloader.cli import run_analysis
run_analysis()
```

--------------------------------

### Initialize AdLibAPI

Source: https://github.com/paularossi/addownloader/blob/main/docs/source/adlib_api.md

Initialize the AdLibAPI object with an access token and an optional project name. Ensure you provide a valid Meta developer token.

```python
>>> from AdDownloader import adlib_api
>>> access_token = input() # your fb-access-token-here
>>> ads_api = adlib_api.AdLibAPI(access_token, project_name = "test1")
```

--------------------------------

### AdDownloader.cli.run_analysis

Source: https://github.com/paularossi/addownloader/blob/main/docs/html/cli.html

The main function to execute the AdDownloader tool, allowing the user to run analyses until they choose to stop.

```APIDOC
## AdDownloader.cli.run_analysis

### Description
Main function to run the AdDownloader tool until the user stops the analysis.

### Method
Not specified (CLI function)

### Endpoint
Not specified (CLI function)
```

--------------------------------

### Initialize AdLibAPI

Source: https://github.com/paularossi/addownloader/blob/main/docs/html/_modules/AdDownloader/adlib_api.html

Initializes the AdLibAPI object with an access token and API version. Sets up the base URL and retrieves available fields.

```python
def __init__(self, access_token, version = "v18.0"):
    """
    Initialize the AdLibAPI object.

    :param access_token: The access token for authentication.
    :type access_token: str
    :param version: The version of the Meta Ad Library API. Default is "v18.0".
    :type version: str
    """
    
    self.version = version
    self.access_token = access_token
    self.base_url = "https://graph.facebook.com/{version}/ads_archive".format(version = self.version)
    self.fields = self.get_fields()
    self.request_parameters = {}
    self.project_name = None
```

--------------------------------

### AdDownloader.cli.run_task_B

Source: https://github.com/paularossi/addownloader/blob/main/docs/html/cli.html

Executes task B, which downloads ads media content based on user selections. It can use a specified Excel file or a default path for ads data.

```APIDOC
## AdDownloader.cli.run_task_B

### Description
Run task B: Download ads media content based on user’s choices.

### Method
Not specified (CLI function)

### Endpoint
Not specified (CLI function)

### Parameters
#### Path Parameters
* **project_name** (str) - Required - The name of the current project.
* **file_name** (str) - Optional - Name of the Excel file containing ads data. If none is provided data is taken from ‘output/project_name/ads/data/original_data.xlsx’
```

--------------------------------

### Initialize AdLib API and Set Parameters

Source: https://github.com/paularossi/addownloader/blob/main/docs/html/_modules/AdDownloader/adlib_api.html

Initializes the AdLib API and sets parameters for ad data retrieval. Handles both page ID lists from Excel files and direct search terms. Ensures valid Excel files are used for page IDs.

```python
def __init__(self, access_token):
        self.base_url = "https://graph.facebook.com/v13.0/ads_archive"
        self.access_token = access_token
        self.request_parameters = {}

    def set_parameters(self, fields=None, countries='NL', start_date="2023-01-01", end_date=None, page_ids=None, search_terms=None, project_name=None):
        """
        Set the parameters for the API request.

        :param fields: The fields to include in the API response. Default is None, fields are retrieved from the created AdLibApi object.
        :type fields: str
        :param countries: The country for ad targeting. Default is 'NL'.
        :type countries: str
        :param start_date: The start date for ad delivery. Default is "2023-01-01".
        :type start_date: str
        :param end_date: The end date for ad delivery. Default is the current date.
        :type end_date: str
        :param page_ids: The file containing page IDs. Default is None. Complementary with search_terms.
        :type page_ids: str
        :param search_terms: The search terms for ad filtering. Default is None. Complementary with page_ids.
        :type search_terms: str
        :param project_name: The name of the project. Default is the current date and time.
        :type project_name: str
        """
        if fields is None:
            fields = self.get_fields()

        self.project_name = project_name

        params = {
            "fields": fields,
            "ad_reached_countries": countries,
            "search_page_ids": None,
            "search_terms": None,
            "ad_delivery_date_min": start_date,
            "ad_delivery_date_max": end_date,
            "limit": "300",
            "access_token": self.access_token
        }

        #TODO: accept additional parameters through kwargs**
        # kwargs.update(fields = fields)
        # headers = kwargs
        # headers += ["&{key}={value}".format(key = str(key), value = str(value)) for key, value in kwargs.items()]
        # print(f"you added the following params: {headers}")

        # page ids - the file must contain at least one column called page_id
        if page_ids is not None:
            if is_valid_excel_file(page_ids):
                path = os.path.join("data", page_ids)
                data = pd.read_excel(path)
                search_page_ids_list = data['page_id'].tolist()
                params["search_page_ids"] = search_page_ids_list
                self.request_parameters = params

        elif search_terms is not None:
            params["search_terms"] = search_terms
            self.request_parameters = params

        else:
            print('You need to specify either pages ids or search terms.')

```

--------------------------------

### AdLibAPI.__init__

Source: https://github.com/paularossi/addownloader/blob/main/docs/html/_sources/adlib_api.rst.txt

Initializes the AdLibAPI class with a Facebook access token.

```APIDOC
## AdLibAPI.__init__

### Description
Initializes the AdLibAPI class with a Facebook access token.

### Method
__init__

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```python
>>> from AdDownloader import adlib_api
>>> access_token = input() # your fb-access-token-here
>>> ads_api = adlib_api.AdLibAPI(access_token)
```

### Response
None
```

--------------------------------

### Initialize AdLibAPI

Source: https://github.com/paularossi/addownloader/blob/main/docs/html/_sources/adlib_api.rst.txt

Instantiate the AdLibAPI class with your Facebook access token.

```python
from AdDownloader import adlib_api
access_token = input() # your fb-access-token-here
ads_api = adlib_api.AdLibAPI(access_token)
```

--------------------------------

### Create Virtual Environment (Windows)

Source: https://github.com/paularossi/addownloader/blob/main/README.md

Create a new virtual environment named 'venv' on Windows. This isolates project dependencies.

```bash
python -m venv venv
```

--------------------------------

### Configure Logging with File Handler

Source: https://github.com/paularossi/addownloader/blob/main/docs/source/helpers.md

Sets up a logger to write messages to a project-specific log file. Ensures handlers are not duplicated to avoid redundant logging.

```python
import logging
import os

def configure_logging(project_name):
    """Configures and returns a logger with a file handler set to write logs to a specified project’s log file.

    This function creates a log file named ‘logs.log’ within a directory named after the project_name under the ‘output’ directory.
    It checks if the logger already has handlers to prevent adding multiple handlers that do the same thing, ensuring
    that each message is logged only once.

    Args:
        project_name (str): The name of the project for which logging is being configured.

    Returns:
        logging.Logger: A configured logger object that logs messages to ‘output/<project_name>/logs.log’.
    """
    log_dir = os.path.join('output', project_name)
    os.makedirs(log_dir, exist_ok=True)
    log_file = os.path.join(log_dir, 'logs.log')

    logger = logging.getLogger(project_name)

    if not logger.handlers:
        file_handler = logging.FileHandler(log_file)
        formatter = logging.Formatter('%(asctime)s - %(name)s - %(levelname)s - %(message)s')
        file_handler.setFormatter(formatter)
        logger.addHandler(file_handler)
        logger.setLevel(logging.INFO)

    return logger
```

--------------------------------

### Fetch Data from API

Source: https://github.com/paularossi/addownloader/blob/main/docs/html/_sources/adlib_api.rst.txt

Fetch data from a specified URL using the API's parameters. Ensure the AdLibAPI instance is initialized.

```python
url = "https://graph.facebook.com/v18.0/ads_archive"
params = ads_api.get_parameters()
api.fetch_data(url, params)
```

--------------------------------

### Analyze Media Data Manually with AdDownloader

Source: https://github.com/paularossi/addownloader/blob/main/docs/source/index.md

Analyzes image data from a specified folder, extracting features like dominant colors, resolution, brightness, contrast, and sharpness. It also supports batch analysis of an entire folder and uses BLIP for image captioning and visual question answering. Ensure the image path is correct and image files are in supported formats (jpg, png, jpeg).

```python
images_path = f"output/test2/ads_images"
image_files = [f for f in os.listdir(images_path) if f.endswith(('jpg', 'png', 'jpeg'))]

### for an individual image
# dominant colors:
dominant_colors, percentages = extract_dominant_colors(os.path.join(images_path, image_files[2]))
for col, percentage in zip(dominant_colors, percentages):
   print(f"Color: {col}, Percentage: {percentage:.2f}%")

# image quality
resolution, brightness, contrast, sharpness = assess_image_quality(os.path.join(images_path, image_files[2]))
print(f"Resolution: {resolution} pixels, Brightness: {brightness}, Contrast: {contrast}, Sharpness: {sharpness}")

# OR - all features together
analysis_result = analyse_image(os.path.join(images_path, image_files[2]))
print(analysis_result)

### for a folder with images
df = analyse_image_folder(images_path)
df.head(5)


### CAPTIONING AND QUESTION ANSWERING WITH BLIP
img_caption = blip_call(images_path, nr_images=20)
img_caption.head(5)

img_content = blip_call(images_path, task="visual_question_answering", nr_images=20, questions="Are there people in this ad?")
img_content.head(5)
```

--------------------------------

### Activate Virtual Environment (Windows)

Source: https://github.com/paularossi/addownloader/blob/main/README.md

Activate the 'venv' virtual environment on Windows. This ensures that project dependencies are used.

```bash
venv\Scripts\activate.bat
```

--------------------------------

### Generating Sphinx Documentation

Source: https://github.com/paularossi/addownloader/blob/main/docs/html/_modules/AdDownloader/cli.html

Command to generate Sphinx documentation for the project. This command builds the documentation in HTML format.

```bash
# to generate the sphinx documentation run 'sphinx-build -M html docs/source docs'
```

--------------------------------

### configure_logging

Source: https://github.com/paularossi/addownloader/blob/main/docs/source/helpers.md

Configures and returns a logger with a file handler set to write logs to a specified project’s log file. It creates a log file named ‘logs.log’ within a directory named after the project_name under the ‘output’ directory.

```APIDOC
## configure_logging Function

### AdDownloader.helpers.configure_logging(project_name)

Configures and returns a logger with a file handler set to write logs to a specified project’s log file.
This function creates a log file named ‘logs.log’ within a directory named after the project_name under the ‘output’ directory.
It checks if the logger already has handlers to prevent adding multiple handlers that do the same thing, ensuring
that each message is logged only once.

* **Parameters:**
  **project_name** (*str*) – The name of the project for which logging is being configured.
* **Returns:**
  A configured logger object that logs messages to ‘output/<project_name>/logs.log’.
* **Return type:**
  logging.Logger
```

--------------------------------

### Activate Virtual Environment (MacOS)

Source: https://github.com/paularossi/addownloader/blob/main/README.md

Activate the 'myenv' virtual environment on MacOS. This ensures that project dependencies are used.

```bash
source myenv/bin/activate
```