Add Markdown output support - #5
Open
jvmvik wants to merge 1 commit into
Open
Conversation
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>
Contributor
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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.
What changed
markdown()on the client, mirroringhtml().search_archive()acceptsmdalongsidejsonandhtml.Client::FORMATS, raw-string formats intoClient::RAW_FORMATS, so the two validation sites and the response branch stop repeating the list.README.mdandREADME.md.erb.Endpoint contract
Probed against the live API before implementing:
/search?output=md200,content-type: text/markdown/search?output=markdown400,Unsupported \markdown` output.`/searches/<id>.mdmarkdown_endpointin the metadatamdis the accepted spelling;markdownis rejected. Worth knowing if anyone adds this to another client library.The payload opens with a YAML front matter block holding
search_metadataandsearch_parameters, followed by the results as Markdown sections.Verification
ClientMarkdownTestcovers format constants,output=mdin the query, and rejection of unsupported formats — all without an API key.text/markdownbody starting with front matter and containing headings.markdown()itself could not be called end-to-end here, since/searchrequires an API key and none was available in this environment; the two live tests inGoogleSearchTestcover that path and will run in CI.For the reviewer
One behaviour change:
search_archive()'s error message goes fromformat must be json or htmltoformat must be json, html or md. Its test is updated. Anyone matching on that string would be affected.Based on
feature/ruby-parity(#3), notInit. This touches the sameget()andsearch_archive()code that #3 rewrote, so basing onInitwould 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