Skip to content

Add Markdown output support - #5

Open
jvmvik wants to merge 1 commit into
feature/ruby-parityfrom
feature/markdown-output
Open

Add Markdown output support#5
jvmvik wants to merge 1 commit into
feature/ruby-parityfrom
feature/markdown-output

Conversation

@jvmvik

@jvmvik jvmvik commented Aug 16, 2026

Copy link
Copy Markdown
Contributor

Adds Markdown output, following the existing html() pattern.

Markdown is useful for feeding results to an LLM or indexing them for RAG: it keeps the structure of the results without the weight of JSON or HTML.

$client = new Client(getenv('SERPAPI_KEY'));
$markdown = $client->markdown(['q' => 'Coffee']);

// and replaying a past search in the same format
$markdown = $client->search_archive($search_id, 'md');

What changed

  • markdown() on the client, mirroring html().
  • search_archive() accepts md alongside json and html.
  • Accepted formats moved into Client::FORMATS, raw-string formats into Client::RAW_FORMATS, so the two validation sites and the response branch stop repeating the list.
  • README section documenting both, in README.md and README.md.erb.

Endpoint contract

Probed against the live API before implementing:

Request Result
/search?output=md 200, content-type: text/markdown
/search?output=markdown 400, Unsupported \markdown` output.`
/searches/<id>.md supported — surfaced as markdown_endpoint in the metadata

md is the accepted spelling; markdown is rejected. Worth knowing if anyone adds this to another client library.

The payload opens with a YAML front matter block holding search_metadata and search_parameters, followed by the results as Markdown sections.

Verification

  • PHPStan level 6: clean. PHPUnit: 120 tests, 0 failures (up from 108).
  • New ClientMarkdownTest covers format constants, output=md in the query, and rejection of unsupported formats — all without an API key.
  • Live check: the exact URL the client builds returns a 12KB text/markdown body starting with front matter and containing headings. markdown() itself could not be called end-to-end here, since /search requires an API key and none was available in this environment; the two live tests in GoogleSearchTest cover that path and will run in CI.

For the reviewer

One behaviour change: search_archive()'s error message goes from format must be json or html to format must be json, html or md. Its test is updated. Anyone matching on that string would be affected.

Based on feature/ruby-parity (#3), not Init. This touches the same get() and search_archive() code that #3 rewrote, so basing on Init would have guaranteed conflicts. Merge #3 first; the diff shown here will then reduce to the markdown change alone.

The version bump for these features is in a separate PR, as requested.

🤖 Generated with Claude Code

SerpApi serves search results as Markdown via `output=md`, useful for
feeding results to an LLM or indexing them for RAG: it keeps the structure
of the results without the weight of JSON or HTML. The client only spoke
json and html.

Add markdown(), mirroring html(), and accept `md` in search_archive() so a
past search can be replayed in the same format.

The accepted formats move into Client::FORMATS, and the raw-string formats
into Client::RAW_FORMATS, so the two validation sites and the response
branch no longer repeat the list. Note that the API rejects `markdown` as an
output value; `md` is the accepted spelling.

Verified against the live API: the URL the client builds returns
text/markdown opening with a YAML front matter block.

The search_archive error message changes from "format must be json or html"
to "format must be json, html or md", and its test with it.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
@jvmvik jvmvik mentioned this pull request Aug 16, 2026
@galetahub

Copy link
Copy Markdown
Contributor

@jvmvik, thanks for working on it! 👍
Markdown support has already been added via this PR #7

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants