cuery.seo.aio.scrapingdog
=========================

.. py:module:: cuery.seo.aio.scrapingdog

.. autoapi-nested-parse::

   API helpers to access Google AI Overview in Google SERP results via ScrapingDog.

   Scraping Dog
   -------------

   Implements a convenience function :func:`query_google` that mirrors the shape of
   ``cuery.search`` provider helpers by returning a ``SearchResult`` (answer + sources)
   extracted from Google AI Overview (aka AI Overviews / AI Summary) when available.

   The ScrapingDog API exposes (at least) two relevant endpoints:

   * ``https://api.scrapingdog.com/google`` – standard SERP results. In some cases
     the AI Overview content may be embedded directly in the JSON payload (future
     proofing – not currently documented in retrieved snippets but handled here).
   * ``https://api.scrapingdog.com/google/ai_overview`` – dedicated endpoint for
     AI Overview content when Google requires a secondary fetch.



Functions
---------

.. autoapisummary::

   cuery.seo.aio.scrapingdog.flatten_text_blocks
   cuery.seo.aio.scrapingdog.parse_aio
   cuery.seo.aio.scrapingdog.aio_api_url
   cuery.seo.aio.scrapingdog.query
   cuery.seo.aio.scrapingdog.gather


Module Contents
---------------

.. py:function:: flatten_text_blocks(blocks)

   Convert list of ``text_blocks`` to a single answer string.

   Supported block types (based on docs sample): ``paragraph`` and ``list``.
   A ``list`` block contains a ``list`` key with items each having ``snippet``.
   Unknown types are ignored (future proof).


.. py:function:: parse_aio(aio)

   Extract AI Overview into a ``SearchResult``.

   Expected structure (subset):
   {
       "ai_overview": {
           "text_blocks": [...],
           "references": [ {"title": str, "link": str, ...}, ... ]
       }
   }


.. py:function:: aio_api_url(aio)

   Extract the API URL from the aio dict, if available.


.. py:function:: query(prompt, country = None, language = None, validate = True, log = False, session = None)
   :async:


   Execute a Google search via ScrapingDog and extract AI Overview.


.. py:function:: gather(prompts, country = None, language = None, validate = True, log = False, session = None, policies = None, execute = True)
   :async:


   Create zero-argument coroutine factories (with policies) for many prompts.