Guide · 4 minutes
Reading the spreadsheet
Every download writes the same table three times over. ads.xlsx is the one to read, ads.csv is the one to import, and ads.json is there if you have your own tooling.
- One row per version
- A carousel with six cards becomes six rows. They share a Library ID and differ by variant_index, so sorting on library_id lines a whole creative test up for you.
- Who ran it
- advertiser_name, page_id and page_url between them pin down who ran it. ad_library_url takes you straight back to that exact ad on the library.
- How long it ran
- started_running, ended_running and is_active. An ad left alone for four months is usually a winner. A burst of new ones in a week is usually a test.
- The copy
- body_text, headline, description, cta_text and cta_type. The words exactly as the library published them, line breaks and emoji included.
- Where it points
- landing_url and link_caption for the destination. video_url is where a Google video ad puts its YouTube link.
- The file on disk
- file_name matches the media in the ZIP exactly, so pairing a row with its image is never guesswork. media_url_quality tells you whether the original was available or only a resized copy.
- How widely it is used
- collation_id and collation_count show how many other ads share the same creative. It is rough, but it is the closest public read you get on how hard an advertiser is pushing something.
- Why a cell is empty
- Because the library did not publish it for that ad. We do not estimate and we do not fill blanks in. The Notes column explains any ad whose media could not be captured.
Opening it
Opening it without mangling the text
Excel and Google Sheets
Open ads.csv straight up. It is UTF-8 with a byte-order mark, which is the small detail that stops Excel turning Hindi, Arabic or emoji into rows of question marks. Or open ads.xlsx, where the columns are already sized and the links are clickable.
Scripts and notebooks
ads.json has the same rows plus the export's own metadata: when it ran, and which library page it came from. Field names match the CSV columns exactly, so nothing needs remapping.
Next
Want a column we do not have?
Tell us what you are trying to work out. If the library publishes it, we will look at adding it.