[audrey-serpapi]

Updates to unify integration doc structure #8336
Summary of changes:

• Added: Features, Response Formats, Configuration, Search Asynchronous, new examples
• Edited: Quickstart
• Reordered: examples, headers like Documentation
• Removed: 'Markdown output for AI agents' section (as it was already included in the response formats section) + some examples to keep the API spotlighted consistent

[strzibny]

Thank you @audrey-serpapi in looking into this. I have some comments.

Styling-wise:

1. Let's only use sentence case
2. Prefer bold text (Google Shopping Light) instead of #### headings for light variants
3. "See documentation" not "See Documentation"
4. Let's drop $ from examples so they are easier to copy (and follows Ruby README), e.g. pip install serpapi not $ pip install serpapi

Text inconsistencies:

1. os.getenv("API_KEY") vs export SERPAPI_KEY (ENV needs to be same everywhere)
2. indentation switches between 2 and 4 spaces
3. import order varies.
4. Quickstart links to /dashboard instead of users/sign_up?plan=free
5. "See the playground" has no link.

Technically wrong for Python:

1. "Set defaults when creating a client, then override search parameters in individual calls" is not possible in Python. This is only a feature of our Ruby library.
2. The engine and async rows ("can be set on the client") are wrong. Neither can be set on the client.
3. The timeout default is not 120. It’s None, which means requests has no timeout at all. (I am thinking if we should add it @adarshdigievo)
4. "for non-persistent HTTP requests" doesn’t apply here as Python always uses a requests.Session.
5. "Search-engine-specific parameters can also be supplied when creating the client" is false.
6. "returns the results as a regular Python Hash": “Hash” is Ruby terminology. Python has dictionary.
7. "a Python Dictionary" should be dict.
8. the section with 'This strategy is I/O usage' doesn't read well, also, in Python people might use concurrent.futures.ThreadPoolExecutor instead of forking, maybe let's write it more generally (" a single process can submit many searches and collect the results later. The code is more complex because you have to track search IDs and check their status.")

[audrey-serpapi]

Thanks for the comments Josef. Addressed these points.
@adarshdigievo could this please get your review and updates?

[strzibny]

Thank you @audrey-serpapi I see most things addressed. I still see a couple of small things:

1, SerpApi Python Library & Package -> SerpApi Python Library (redundant)

2. ### Search asynchronously - ### Asynchronous searches (let's keep noun like everything else)

3. ### Search Bing -> ### Bing Search (again let's try to do it the same and use nouns) + same with other engines like DuckDuckGo, Baidu, Amazon

4. ## Basic examples in Python -> ## Examples (we are already talking about Python the whole time)

5. The Features bullet says “token-efficient Markdown with md, or raw search-engine HTML with html” Let's specifically say "output" as a keyword here so that it's clear? I say that because we don't talk about client.md() method, but perhaps these md and html methods can be added for convenience as we have in Ruby (cc @adarshdigievo)

6. "Use search and default output (none)” is awkward. “Use search without output” is clearer.

7. Maybe we can link to Playground and the integration page (similarly how we do in Ruby)

[adarshdigievo]

AI disclosure: Codex (GPT-6 Astra, xhigh) made the documentation edits and ran checks. Claude Opus 5.5 (xhigh) reviewed the drafts.

Note: AI made these edits based on my manual suggestions and the review findings I agreed to include. The reasons for the changes are below:

• Simplify the examples: Replaced pprint() with print() to avoid an extra import. Standardized API key access using os.environ["SERPAPI_KEY"] (instead of os.environ.get()) so a missing environment variable fails immediately.

• Keep the README concise: This appears on both GitHub and the PyPI package page, so I wanted to keep it short and simple. I removed/simplified detailed polling and parameter-configuration examples from the last commit. Below two points are examples of this.

• Simplify configuration: Kept only api_key and timeout, with their defaults and descriptions, matching the current client constructor. Removed the extra parameter-routing table and repeated setup example.

• Clarify async behavior: Made the distinction from Python asyncio explicit. SerpApi processes the search job asynchronously, while each Python SDK call remains synchronous. Replaced the long queue example with a short submit-and-retrieve example and linked to polling guidance with timeouts and a deadline.

• Clarify results and output formats: Described JSON results accurately as dict-like SerpResults objects and included as_dict() for serialization. Made the format choices clearer: JSON for structured processing, Markdown for direct LLM input, and HTML for inspecting or processing the raw response.

• Include the Extract API: Added an example for the recently merged extract() method. Placed it after Google Shopping and Google Images so readers encounter familiar APIs first. Kept one main example and linked to Map Mode and Crawl Mode.

• Improve onboarding and migration guidance: Added a full-documentation callout near the top and a getting-started link for Windows setup and saving/running examples. Moved migration guidance below Features because it is relevant mainly to users of the older package.

• Make resources easier to find: Renamed the section to “More resources,” gave Playground its own subsection for building and testing requests, and grouped the AI agent guide and llms.txt under “For agents.” Removed the history and integration links from this section and explained the status metrics link.

• Make examples more reliable: Updated Flights to use future dates and handle other_flights when best_flights is absent. Replaced placeholder error handling with explicit failures and a check for an API error field.

• Apply the writing style: Used sentence case for ordinary headings and labels while preserving proper nouns, API names, and SerpApi feature capitalization.

@audrey-serpapi and @strzibny, could you review these changes?

[strzibny]

LGTM, I would probably not separate Playground as a subheading or at least also use a bullet point so the section feels uniform.