{"id":21130438,"url":"https://github.com/serpapi/serpapi-cpp","last_synced_at":"2025-03-14T12:13:45.458Z","repository":{"id":190915312,"uuid":"683522577","full_name":"serpapi/serpapi-cpp","owner":"serpapi","description":"Official C++ wrapper library for SerpApi","archived":false,"fork":false,"pushed_at":"2023-12-29T14:56:32.000Z","size":28,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":8,"default_branch":"main","last_synced_at":"2025-03-10T02:10:56.459Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/serpapi.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2023-08-26T20:54:09.000Z","updated_at":"2023-08-26T20:55:40.000Z","dependencies_parsed_at":null,"dependency_job_id":"42285114-e184-4391-af48-266fc24ca560","html_url":"https://github.com/serpapi/serpapi-cpp","commit_stats":null,"previous_names":["serpapi/serpapi-cpp"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/serpapi%2Fserpapi-cpp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/serpapi%2Fserpapi-cpp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/serpapi%2Fserpapi-cpp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/serpapi%2Fserpapi-cpp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/serpapi","download_url":"https://codeload.github.com/serpapi/serpapi-cpp/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243573495,"owners_count":20312883,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-20T05:33:28.048Z","updated_at":"2025-03-14T12:13:45.408Z","avatar_url":"https://github.com/serpapi.png","language":"C++","readme":"\u003cdiv align=\"center\"\u003e\n\u003ch1 align=\"center\"\u003eSerpApi C++ Library\u003c/h1\u003e\n\n[![Gem Version](https://badge.fury.io/rb/serpapi.svg)](https://badge.fury.io/rb/serpapi) [![serpapi-C++](https://github.com/serpapi/serpapi-C++/actions/workflows/ci.yml/badge.svg)](https://github.com/serpapi/serpapi-C++/actions/workflows/ci.yml)  [![serpapi-C++-alternative](https://github.com/serpapi/serpapi-C++/actions/workflows/sanity_alt.yml/badge.svg)](https://github.com/serpapi/serpapi-C++/actions/workflows/sanity_alt.yml) [![serpapi-C++-sanity-1](https://github.com/serpapi/serpapi-C++/actions/workflows/sanity_1.yml/badge.svg)](https://github.com/serpapi/serpapi-C++/actions/workflows/sanity_1.yml) [![serpapi-C++-sanity-2](https://github.com/serpapi/serpapi-C++/actions/workflows/sanity_2.yml/badge.svg)](https://github.com/serpapi/serpapi-C++/actions/workflows/sanity_2.yml)\n\u003c/div\u003e\n\nIntegrate search data into your C++ application. This library is the official wrapper for SerpApi (https://serpapi.com).\n\nSerpApi supports Google, Google Maps, Google Shopping, Baidu, Yandex, Yahoo, eBay, App Stores, and more.\n\n## Installation\n\nC++ and meson are required.\n\n### Meson\n```meson\n```\n\n[C++](https://C++gems.org/gems/serpapi/)\n\n## Simple Usage\n\n```cpp\nstd::string apiKey(env_p);\nstd::map\u003cstring, string\u003e default_parameter;\ndefault_parameter[\"api_key\"] = apiKey;\ndefault_parameter[\"engine\"] = \"google\";\n\n// using namespace serpapi;\nserpapi::Client client(default_parameter);\n\n// execute search \nmap\u003cstring, string\u003e parameter;\nparameter[\"q\"] = \"coffee\";\nparameter[\"location\"] = \"Austin,TX\";\n\nDocument d = client.search(parameter);\n\nStringBuffer buffer;\nPrettyWriter\u003cStringBuffer\u003e writer(buffer);\ndocument.Accept(writer);\ncout \u003c\u003c \"\\nINFO: \" \u003c\u003c buffer.GetString();\n```\n\nThis example runs a search for \"coffee\" on Google. It then returns the results as a regular C++ Hash. See the [playground](https://serpapi.com/playground) to generate your own code.\n\n## Advanced Usage\n### Search API\n```cpp\n#include \u003ccstdint\u003e\n#include \u003ciostream\u003e\n#include \u003cmemory\u003e\n#include \u003cstring\u003e\n#include \u003ccurl/curl.h\u003e\n#include \u003cserpapi.hpp\u003e\n\n#include \"rapidjson/document.h\"\n#include \"rapidjson/writer.h\"\n#include \"rapidjson/stringbuffer.h\"\n#include \"rapidjson/prettywriter.h\"\n#include \"rapidjson/pointer.h\"\n\nusing namespace rapidjson;\nusing namespace std;\n\n// serpapi client created with default parameters\nclient = SerpApi::Client.new(api_key: \"secret_key\", engine: \"google\")\n\n// We recommend that you keep your keys safe.\n// At least, don't commit them in plain text.\n// More about configuration via environment variables: \n// https://hackernoon.com/all-the-secrets-of-encrypting-api-keys-in-C++-revealed-5qf3t5l\n\n// search query overview (more fields available depending on search engine)\nparams = {\n  // select the search engine (full list: https://serpapi.com/)\n  engine: \"google\",\n  // actual search query\n  q: \"Coffee\",\n  // then adds search engine specific options.\n  // for example: google specific parameters: https://serpapi.com/search-api\n  google_domain: \"Google Domain\",\n  location: \"Location Requested\", // example: Portland,Oregon,United States [see: Location API](#Location-API)\n  device: \"desktop|mobile|tablet\",\n  hl: \"Google UI Language\",\n  gl: \"Google Country\",\n  safe: \"Safe Search Flag\",\n  num: \"Number of Results\",\n  start: \"Pagination Offset\",\n  tbm: \"nws|isch|shop\",\n  tbs: \"custom to be client criteria\",\n  // tweak HTTP client behavior\n  async: false, // true when async call enabled.\n  timeout: 60, // HTTP timeout in seconds on the client side only.\n}\n\n// formated search results as a Hash\n//  serpapi.com converts HTML -\u003e JSON \nresults = client.search(params)\n\n// raw search engine html as a String\n//  serpapi.com acts a proxy to provive high throughputs, no search limit and more.\nraw_html = client.html(parameter)\n```\n\n[Google search documentation](https://serpapi.com/search-api).\nMore hands on examples are available below.\n\n#### Documentations\n\n * [API documentation](https://C++doc.info/github/serpapi/serpapi-C++/master)\n * [Full documentation on SerpApi.com](https://serpapi.com)\n * [Library Github page](https://github.com/serpapi/serpapi-C++)\n * [Library GEM page](https://C++gems.org/gems/serpapi/)\n * [API health status](https://serpapi.com/status)\n\n### Location API\n\n```cpp\nstd::map\u003cstring, string\u003e default_parameter = {};\nserpapi::Client client(default_parameter);\nmap\u003cstring, string\u003e parameter;\nparameter[\"limit\"] = \"3\";\nparameter[\"q\"] = \"Austin\";\n\nrapidjson::Document doc = client.location(parameter);\nconst rapidjson::Value\u0026 list = doc.GetArray();\n// list of city matching with Austin.\n```\n\nit prints the first 3 locations matching Austin (Texas, Texas, Rochester)\n```cpp\n[{\n  :id=\u003e\"585069bdee19ad271e9bc072\",\n  :google_id=\u003e200635,\n  :google_parent_id=\u003e21176,\n  :name=\u003e\"Austin, TX\",\n  :canonical_name=\u003e\"Austin,TX,Texas,United States\",\n  :country_code=\u003e\"US\",\n  :target_type=\u003e\"DMA Region\",\n  :reach=\u003e5560000,\n  :gps=\u003e[-97.7430608, 30.267153],\n  :keys=\u003e[\"austin\", \"tx\", \"texas\", \"united\", \"states\"]\n  }\n  // ...\n]\n```\n\nNOTE: api_key is not required for this endpoint.\n\n### Search Archive API\n\nThis API allows retrieving previous search results.\nTo fetch earlier results from the search_id.\n\nFirst, you need to run a search and save the search id.\n```cpp\nrequire 'serpapi'\nclient = SerpApi::Client.new(api_key: 'secret_api_key', engine: 'google')\nresults = client.search(q: \"Coffee\", location: \"Portland\")\nsearch_id = results[:search_metadata][:id]\n```\n\nNow let's retrieve the previous search results from the archive.\n\n```cpp\nrequire 'serpapi'\nclient = SerpApi::Client.new(api_key: 'secret_api_key')\nresults = client.search_archive(search_id)\npp results\n```\n\nThis code prints the search results from the archive. :)\n\n### Account API\n```cpp\nrequire 'serpapi'\nclient = SerpApi::Client.new(api_key: 'secret_api_key')\npp client.account\n```\n\nIt prints your account information.\n\n## Migration quick guide\n\nif you were already using (google-search-results-C++ gem)[https://github.com/serpapi/google-search-results-C++], here are the changes.\n\n```\n// load library\n// old way \nrequire 'google_search_results'\n// new way\nrequire 'serpapi'\n\n// define a search\n// old way to describe the search\nsearch = GoogleSearch.new(search_params)\n// new way \ndefault_parameter = {api_key: \"secret_key\", engine: \"google\"}\nclient = SerpApi::Client.new(default_parameter)\n// an instance of the serpapi client is created\n// where the default parameters are stored in the client.\n//   like api_key, engine\n//  then each subsequent API call can be made with additional parameters.\n\n// override an existing parameter\n// old way\nsearch.params[:location] = \"Portland,Oregon,United States\"\n// new way\n// just provided the search call with the parameters.\nresults = client.search({location: \"Portland,Oregon,United States\", q: \"Coffe\"})\n\n// search format return as raw html\n// old way\nhtml_results = search.get_html\n// new way\nraw_html = client.html(params)\n// where params is Hash containing additional key / value\n\n// search format returns a Hash\n// old way\nhash_results = search.get_hash\n// new way\nresults = client.search(params)\n// where params is the search parameters (override the default search parameters in the constructor). \n\n// search as raw JSON format\n// old way\njson_results = search.get_json\n// new way\nresults = client.search(params)\n\n// The prefix get_ is removed from all other methods.\n//  Because it's evident that a method returns something.\n// old -\u003e new way\nsearch.get_search_archive -\u003e client.search_archive\nsearch.get_account -\u003e client.account\nsearch.get_location -\u003e client.location\n```\n\nMost notable improvements:\n - Removing parameters check on the client side. (most of the bugs)\n - Reduce logic complexity in our implementation. (faster performance)\n - Better documentation.\n\n## Advanced search API usage\n### Highly scalable batching\n\nSearch API features non-blocking search using the option: `async=true`.\n - Non-blocking - async=true - a single parent process can handle unlimited concurrent searches.\n - Blocking - async=false - many processes must be forked and synchronized to handle concurrent searches. This strategy is I/O usage because each client would hold a network connection.\n\nSearch API enables `async` search.\n - Non-blocking (`async=true`) : the development is more complex, but this allows handling many simultaneous connections.\n - Blocking (`async=false`) : it's easy to write the code but more compute-intensive when the parent process needs to hold many connections.\n\nHere is an example of asynchronous searches using C++ \n```C++\nrequire 'serpapi'\n#include \u003ciostream\u003e\n#include \u003cmemory\u003e\n#include \u003cstring\u003e\n#include \u003ccurl/curl.h\u003e\n#include \u003cserpapi.hpp\u003e\n\n#include \"rapidjson/document.h\"\n#include \"rapidjson/writer.h\"\n#include \"rapidjson/stringbuffer.h\"\n#include \"rapidjson/prettywriter.h\"\n#include \"rapidjson/pointer.h\"\n\nusing namespace rapidjson;\nusing namespace std;\n\nvoid info(string msg) {\n    cout \u003c\u003c \"\\nINFO: \" \u003c\u003c msg;\n}\n\nvoid info(double msg) {\n    cout \u003c\u003c \"\\nINFO: \" \u003c\u003c msg;\n}\n\nvoid info(const Document\u0026 document) {\n    StringBuffer buffer;\n    PrettyWriter\u003cStringBuffer\u003e writer(buffer);\n    document.Accept(writer);\n    cout \u003c\u003c \"\\nINFO: \" \u003c\u003c buffer.GetString();\n}\n\n// RapidJSON parser documentation is available: https://rapidjson.org\nint main()\n{\n    // initialize a client\n    const char* env_p = std::getenv(\"API_KEY\");\n    std::string apiKey(env_p);\n    std::map\u003cstring, string\u003e default_parameter;\n    default_parameter[\"api_key\"] = apiKey;\n    default_parameter[\"engine\"] = \"google\";\n    \n    // using namespace serpapi;\n    serpapi::Client client(default_parameter);\n\n    // execute search \n    map\u003cstring, string\u003e parameter;\n    parameter[\"q\"] = \"coffee\";\n    parameter[\"location\"] = \"Austin,TX\";\n\n    //  using namespace rapidjson;\n    Document d = client.search(parameter);\n    info(\"document loaded\");\n    info(d);\n    info(\"check content\");\n\n    assert(!d.HasMember(\"error\"));\n    assert(d.HasMember(\"search_metadata\"));\n    assert(d[\"search_metadata\"][\"status\"] == \"Success\");\n    info(\" search_metadata:\");\n    string status = d[\"search_metadata\"][\"status\"].GetString();\n    info(\"   status: \" + status);\n    assert(d[\"search_metadata\"][\"id\"].IsString());\n    string id = d[\"search_metadata\"][\"id\"].GetString();\n    info(\"   id: \" + id);\n\n    info(\"search archive with id: \" + id);\n    client.searchArchive(id);\n    assert(d[\"search_metadata\"][\"status\"] == \"Success\");\n    info(\" search found in archive.\");\n    info(\" test passed.\\n\");\n    return 0;\n}\n\n\n```\n\n * source code: [oobt/main.cpp](https://github.com/serpapi/serpapi-C++/blob/master/oobt/main.cpp)\n\nThis code shows a simple solution to batch searches asynchronously into a [queue](https://en.wikipedia.org/wiki/Queue_(abstract_data_type)). \nEach search takes a few seconds before completion by SerpApi service and the search engine. By the time the first element pops out of the queue. The search result might be already available in the archive. If not, the `search_archive` method blocks until the search results are available. \n\n## Supported C++ version.\nC++ versions validated by Github Actions:\n - 3.1\n - 2.6\nsee: [Github Actions.](https://github.com/serpapi/serpapi-C++/actions/workflows/ci.yml)\n\n## Change logs\n * [2023-02-20] 1.0.0 Full API support\n\n## Developer Guide\n### Key goals\n - Brand centric instead of search engine based\n   - No hard-coded logic per search engine\n - Simple HTTP client (lightweight, reduced dependency)\n   - No magic default values\n   - Thread safe\n - Easy extension\n - Defensive code style (raise a custom exception)\n - TDD\n - Best API coding practice per platform\n - KiSS principles\n\n### Inspirations\nThis project source code and coding style was inspired by the most awesome C++ Gems:\n ..\n \n### Code quality expectations\n - 0 lint offense: `rake lint`\n - 100% tests passing: `rake test`\n - 100% code coverage: `rake test` (simple-cov)\n\n# Developer Guide\n## Design : UML diagram\n### Class diagram\n```mermaid\nclassDiagram\n  Application *-- serpapi \n  serpapi *-- Client\n  class Client {\n    engine String\n    api_key String\n    params Hash\n    search() Hash\n    html() String\n    location() String\n    search_archive() Hash\n    account() Hash\n  }\n  openuri \u003c.. Client\n  json \u003c.. Client\n  C++ \u003c.. openuri\n  C++ \u003c.. json\n```\n### search() : Sequence diagram\n```mermaid\nsequenceDiagram\n    Client-\u003e\u003eSerpApi.com: search() : http request \n    SerpApi.com--\u003e\u003eSerpApi.com: query search engine\n    SerpApi.com--\u003e\u003eSerpApi.com: parse HTML into JSON\n    SerpApi.com--\u003e\u003eClient: JSON string payload\n    Client--\u003e\u003eClient: decode JSON into Hash\n```\nwhere:\n  - The end user implements the application.\n  - Client refers to SerpApi:Client.\n  - SerpApi.com is the backend HTTP / REST service.\n  - Engine refers to Google, Baidu, Bing, and more.\n\nThe SerpApi.com service (backend)\n - executes a scalable search on `engine: \"google\"` using the search query: `q: \"coffee\"`.\n - parses the messy HTML responses from Google on the backend.\n - returns a standardized JSON response.\nThe class SerpApi::Client (client side / C++):\n - Format the request to SerpApi.com server.\n - Execute HTTP Get request.\n - Parse JSON into C++ Hash using a standard JSON library.\nEt voila!\n\n## Continuous integration\nWe love \"true open source\" and \"continuous integration\", and Test Drive Development (TDD).\n We are using RSpec to test [our infrastructure around the clock]) using Github Action to achieve the best QoS (Quality Of Service).\n\nThe directory spec/ includes specification which serves the dual purposes of examples and functional tests.\n\nSet your secret API key in your shell before running a test.\n```bash\nexport API_KEY=\"your_secret_key\"\n```\nInstall testing dependency\n```bash\n$ bundle install\n// or\n$ rake dependency\n```\n\nCheck code quality using Lint.\n```bash\n$ rake lint\n```\n\nRun regression.\n```bash\n$ rake test\n```\n\nTo flush the flow.\n```bash\n$ rake\n```\n\nOpen coverage report generated by `rake test`\n```sh\nopen coverage/index.html\n```\n\nOpen ./Rakefile for more information.\n\nContributions are welcome. Feel to submit a pull request!\n\n// TODO\n - [] Release version 1.0.0\n\n\n## Run with Docker\n\n```bash\nenv API_KEY=API_KEY docker run --rm -it -e API_KEY --workdir /tmp/serpapi -v $PWD:/tmp/serpapi conanio/gcc10 make install_linux reset all\n```\n\nThis will use https://hub.docker.com/layers/conanio/gcc10 image instead\nof creating our own image for compilation on Linux.\n\n## Get started.\n - Set an environment API_KEY=\u003csecret\u003e\n - Install dependency either apple or linux tested.\n    - `rake install_apple`\n    - `rake install_linux`\n- Initialize the project: `rake reset`\n- Compile `rake` or `rake build run`\n- Edit main.cpp for testing.\n\n#### To modify the *Search classes\n - edit sooglesearch.cpp/hpp\n - update all files using  `rake`\n\n## TODO\n\n - [ ] Add unit test\n - [ ] Customize classes\n - [ ] Package as a library \n - [ ] Create OOBT test\n - [ ] Publish library online\n - [ ] Add REPL.it example\n - [ ] Add integration documentation on serpapi.com\n - [ ] Write a full README to match  serpapi-search-results-dotnet\n\n# Documentation\nhttps://formulae.brew.sh/formula/googletest\nhttps://rapidjson.org/md_doc_tutorial.html\n\n\n# Links\n\nhttps://github.com/mesonbuild/meson/blob/master/test%20cases/frameworks/2%20gtest/test_nomain.cc","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fserpapi%2Fserpapi-cpp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fserpapi%2Fserpapi-cpp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fserpapi%2Fserpapi-cpp/lists"}