Add initial Markdown support by strzibny · Pull Request #29 · serpapi/serpapi-ruby · GitHub

This is WIP change for Markdown support.

Maybe we should call this .md() instead of .markdown() to align with serpapi/serpapi-python#39

Why separate format and output arguments?

Maybe we should call this .md() instead of .markdown() to align with serpapi/serpapi-python#39

Personally I prefer markdown() over md()

Thanks @trusche for having a look. You are right on search_archive, we should cleanly just pass the extension. I fixed it.

Personally I prefer markdown() over md()

Well, that's how I started as well :) However, consistency among our clients is more important I think (already in Python and PHP libs) and I think there is a tiny advantage of matching the extension.

Ruby and rails offer a lot of syntactic sugar, we could at least create an alias?

I was thinking about it, but on the other hand I want us to be direct in docs and want to send people to one method everywhere. So creating an alias just on its own doesn't feel that good to me.

json, html, md are all shortcuts/abbreviations and in that sense it just works in uniform. I think that in the end uniformity among the abbreviations and across the libraries is just more important. They also directly suggest the extension in their meaning.

Do you think it's still worth it?

@strzibny Thanks for the efforts. Functionality wise everything looks good to me 👍

One minor thing I observed (not due to code changes as part of this PR) is that when I pass output: "md" or output: "html" as a parameter in my SerpApi params then my output response for search method is broken with JSON parse related errors (since we default decoder to json. For any other values, for example output: "markdown" we throw an error instead of a broken response. Should we also throw an error for this? maybe we can check under a new issue.

I feel it would be good to mention some sample code in our Readme doc. Something like below where we are differentiating the three,

# For JSON output
result_json     = serpapi_client.search

# For HTML output
result_html     = serpapi_client.html

# For Markdown output
result_md       = serpapi_client.md

Note - I observe that our python library supports output in params so maybe in the future we can also support it in Ruby.

LGTM 👍

Thanks @pulkitchowdry, you are right, we should have already been choosing the right decoder for HTML. I included it in this change.

@strzibny Thanks for the changes. Output parameter is working now!

One issue I observed is that when we do not pass output = "html" and call serpapi_client.html(q: "coffee") then the response is json and not in html format. Should this be like below?

Suggested change

      
                  get('/search', :html, params)
          
                  get('/search.html', :html, params)

Other tests I performed are mismatch between output parameter and the method called and it works properly. Its response is similar to SerpApi cURL response - for example if output parameter is json but we call .html then we respond with json which is fine as the output parameter is taking priority like the main SerpApi.

@pulkitchowdry Great find. I realized we need to fix it a bit better. If we only use search.html route we still have a case where client.md(output: "json") would use the Markdown decoder and return JSON as a raw string rather than a Ruby Hash.

I made a change to always return hash on output=json, string otherwise, basically doing what we do at the server side since /search.md?q=coffee&output=json gives output the preference. So I am matching this behavior.

I think the md, json and html methods should simply not support the output parameters - they're basically shortcuts to search. Let's remove it from the documentation and ignore any passed-in output for these methods? Only search() should support it, with :json as the default.

I think you are right @trusche it also overly complicates 'what should we do'. I still kept CONTENT_TYPE_DECODERS because with this change we can properly show errors that server returns as JSON. Wdyt?

I still don't get why we need separate decoder and output arguments. Would it ever be used with different formats?

Would you be more happy with something like this?

def response_decoder(response, default)
  output = response.headers['Content-Type'].to_s.split(%r{[/;]})[1]
  output = 'md' if output == 'markdown'
  OUTPUT_DECODERS.fetch(output, default)
end

Not sure if I understand what you are asking but running client.md(...) will have to process JSON in case of errors.

And in another case client.send(:get, '/invalid', :json, {}) is returning HTML with text/html content type. So the idea is to process responses by the content type we actually get from serpapi.com

running client.md(...) will have to process JSON in case of errors.

Right, that makes sense.

Thanks @strzibny, LGTM, nice work and some good bug fixes to boot. Approved with a couple of suggestions.

Suggested change

      
                  params = params.reject { |key, _| key.to_s == 'output' }.merge(output: 'html') if params.instance_of?(Hash)
          
                  params = params.reject { |key, _| key.to_s == 'output' }.merge(output: 'html') if params.is_a?(Hash)

Because of this:

[1] pry(main)> HashWithIndifferentAccess.new.instance_of?(Hash)
=> false
[2] pry(main)> HashWithIndifferentAccess.new.is_a?(Hash)
=> true

Nitpick: Duplicated with the only difference being the format. Might be worth extracting to a method:

def force_output(params, format)
  params.reject { |k, _| k.to_s == 'output' }.merge(output: format)
end

Might be worth calling out the behaviour change on get('/invalid'), which now raises a 404

👍

Thanks @trusche I added your final suggestions.

strzibny mentioned this pull request Aug 17, 2026

Add initial Markdown support #28

Closed

Add initial Markdown support

379f946

strzibny force-pushed the markdown branch from cea26e4 to 379f946 Compare August 17, 2026 08:27

strzibny added 3 commits August 17, 2026 10:47

Rename markdown method to md

3fb5120

Update archive to :md

b063cf8

Remove double and keep only live tests

21b5347

strzibny requested review from andypple83, pulkitchowdry and trusche August 18, 2026 09:00

trusche reviewed Aug 18, 2026

View reviewed changes

Pass .md directly in search_archive

d006bcb

pulkitchowdry approved these changes Aug 19, 2026

View reviewed changes

strzibny added 3 commits August 19, 2026 13:39

Choose the right decoder based on output parameter

086f6f8

Include json explicitely

3d41fe7

Join response handling into process_text_response

fb033a1

pulkitchowdry reviewed Aug 20, 2026

View reviewed changes

Introduce response type decoders to always return expected type

385cab6

Keep .md and .html methods as pure shortcuts

39b7e3b

trusche reviewed Aug 20, 2026

View reviewed changes

Comment thread lib/serpapi/client.rb Outdated

trusche reviewed Aug 20, 2026

View reviewed changes

strzibny added 3 commits August 20, 2026 12:36

Do not change query signature

ce01fc3

Do not change query signature

c6b1075

Update spec

1c351bc

trusche approved these changes Aug 25, 2026

View reviewed changes

strzibny added 2 commits August 25, 2026 12:18

Address review recommendations

ea4be3b

Increase Metrics/ClassLength

10a324d

strzibny merged commit bfc0f8b into master Aug 25, 2026
1 check passed

+                  # @param [String|Symbol, nil] output response format using the SerpApi output parameter [optional]
+                  # @return [String|Hash] raw HTML, Markdown, or JSON / Hash
+                  def search_archive(search_id, format = :json, output: nil)
+                    format = output.to_s.to_sym unless output.nil?

-                    response = execute_request(endpoint, params)
-                    handle_response(response, decoder, endpoint, params)
+                  # @return [String|Hash] raw text or decoded response as JSON / Hash
+                  def get(endpoint, decoder = :json, params = {}, output: nil)

-                  # @return [String] raw html search results directly from the search engine.
+                  # @return [String] raw HTML search results.
                   def html(params = {})
+                    params = params.reject { |key, _| key.to_s == 'output' }.merge(output: 'html') if params.instance_of?(Hash)

+                  # @param [Hash] params includes engine, api_key, search fields and more.
+                  # @return [String] search results formatted as Markdown.
+                  def md(params = {})
+                    params = params.reject { |key, _| key.to_s == 'output' }.merge(output: 'md') if params.instance_of?(Hash)

-                    handle_response(response, decoder, endpoint, params)
+                    handle_response(response, response_decoder(response, decoder), endpoint, params)
+                  ensure
+                    response&.flush if persistent?

		@@ -123,6 +125,15 @@ def html(params = {})
		get('/search', :html, params)

	get('/search', :html, params)
	get('/search.html', :html, params)

	params = params.reject { \|key, _\| key.to_s == 'output' }.merge(output: 'html') if params.instance_of?(Hash)
	params = params.reject { \|key, _\| key.to_s == 'output' }.merge(output: 'html') if params.is_a?(Hash)

		@@ -1,4 +1,5 @@
		# Changelog
		* [Unreleased] Add Markdown search and archive output support

+                  def process_text_response(response, endpoint, params, decoder)
+                    raise_http_error(response, nil, endpoint, params, decoder: decoder) if response.status != 200
+                    response.body.to_s

Add initial Markdown support by strzibny · Pull Request #29 · serpapi/serpapi-ruby · GitHub

Uh oh!

Add initial Markdown support - #29

Add initial Markdown support#29strzibny merged 15 commits intomasterserpapi/serpapi-ruby:masterfrom markdownserpapi/serpapi-ruby:markdownCopy head branch name to clipboard

Conversation

strzibny commented Aug 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

strzibny commented Aug 17, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

trusche commented Aug 18, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

strzibny commented Aug 18, 2026

Uh oh!

trusche commented Aug 18, 2026

Uh oh!

strzibny commented Aug 18, 2026

Uh oh!

pulkitchowdry commented Aug 19, 2026

Uh oh!

pulkitchowdry left a comment

Choose a reason for hiding this comment

Uh oh!

strzibny commented Aug 19, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

strzibny commented Aug 20, 2026

Uh oh!

trusche commented Aug 20, 2026

Uh oh!

strzibny commented Aug 20, 2026

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

trusche commented Aug 25, 2026

Uh oh!

trusche left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

strzibny commented Aug 25, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Add initial Markdown support#29
strzibny merged 15 commits into
masterfrom
markdown

strzibny commented Aug 17, 2026 •
edited
Loading

trusche commented Aug 18, 2026 •
edited
Loading