Blocking ads, cookie banners, trackers and chats

Four options clear away the usual clutter.

curl "https://curlshot.com/api/v1/screenshot?access_key=YOUR_ACCESS_KEY\
&url=https://en.wikipedia.org/wiki/Eiffel_Tower\
&block_ads=true\
&block_trackers=true\
&block_cookie_banners=true\
&block_chats=true" \
  --output eiffel-clean.png

You get the page without ad slots, consent pop-ups or chat bubbles, where the site had any. On a page with none of these, the screenshot is the same as before.

#How blocking works

A web page is not one file. The browser fetches dozens of extra files: scripts, images, fonts, ads. Each fetch is called a request.

Blocking stops some of those requests before they leave the browser. An ad whose script never loads never appears. As a bonus, the page often renders faster.

The page you asked for is never blocked. Only the extra files it pulls in are checked.

All four switches are off by default, so a plain request shows the page as a first-time visitor sees it.

#The four switches

#block_ads

Stops requests to known advertising networks.

The default is false.

Use it for clean previews and thumbnails. The space an ad would have filled may stay empty, depending on how the site is built.

#block_trackers

Stops known analytics and tracking scripts. These record visits and do not usually draw anything.

The default is false.

The screenshot rarely changes. The gain is speed, and your captures do not show up as visits in the site's statistics.

#block_cookie_banners

Removes cookie consent pop-ups.

The default is false.

It works in three ways. It stops the scripts of well-known consent tools from loading. It hides the banner layouts those tools use. And for a banner it does not recognise, it looks for a consent dialog and presses one of its buttons to close it.

#block_chats

Stops live-chat widgets, the "Can I help you?" bubbles in the corner.

The default is false.

#Block a whole kind of file

#block_resources

Blocks every request of the given types.

There is no default. Leave it out and nothing is blocked by type.

The allowed values are document, stylesheet, image, media, font, script, xhr, fetch, websocket, texttrack, eventsource, manifest and other.

This is a list option. Separate the values with commas.

curl "https://curlshot.com/api/v1/screenshot?access_key=YOUR_ACCESS_KEY&url=https://github.com/microsoft/playwright&block_resources=font,media" \
  --output playwright-light.png

The page is drawn with fallback fonts, and video and audio files are never fetched.

The most useful values:

document covers pages embedded inside the page, such as iframes. xhr and fetch are the data requests a page makes after it has loaded.

#Block specific addresses

#block_requests

Blocks requests whose address matches one of your patterns.

There is no default. Leave it out and no pattern is applied.

A pattern is a piece of text with an optional * wildcard. The * stands for any run of characters.

There are two rules to remember:

• A pattern without * matches when the text appears anywhere in the address.
• A pattern with * must describe the whole address, from start to end. So start it with * unless you write the full https:// part.

Upper and lower case are treated the same.

curl -G "https://curlshot.com/api/v1/screenshot" \
  --data-urlencode "access_key=YOUR_ACCESS_KEY" \
  --data-urlencode "url=https://github.com/microsoft/playwright" \
  --data-urlencode "block_requests=*.githubusercontent.com/*" \
  --output playwright-no-avatars.png

You get the repository page without the avatars and other images that GitHub serves from that host.

You can send up to 50 patterns. Separate them with commas, or repeat the option. Since the comma is the separator, a single pattern cannot contain one.

To find what to block, open the page in your browser, press F12 and look at the Network tab. It lists every request the page makes.

#Blocking is best-effort

These options catch the common cases. They do not catch everything, and it is better that you know this up front.

• The lists cover widely used ad, tracking, chat and consent services. A small or regional service may not be on them.
• A site can serve ads from its own address, where they look like normal content.
• A home-made cookie banner may have no button we recognise.
• When a banner is closed by pressing a button, the choice made is whichever button was found. If the capture must reflect a specific choice, set it up yourself with cookies or click.

When something slips through, hide it yourself. hide_selectors removes any element you can point at with a CSS selector. A selector is a short pattern that names an element, such as #promo-bar for the element with the id promo-bar.

curl -G "https://curlshot.com/api/v1/screenshot" \
  --data-urlencode "access_key=YOUR_ACCESS_KEY" \
  --data-urlencode "url=https://en.wikipedia.org/wiki/Eiffel_Tower" \
  --data-urlencode "block_cookie_banners=true" \
  --data-urlencode "hide_selectors=#siteNotice,.vector-sticky-header" \
  --output eiffel-no-notices.png

The two work well together. Blocking handles the known cases across every site. hide_selectors handles the one stubborn element on the site you care about.

#Where to go next

• Custom CSS, JavaScript and clicks: hide, restyle and click things yourself.
• Waiting and timing: give late pop-ups time to show up, so they can be removed.
• Options reference: the blocking options with their limits.