Merge pull request #9 from serpapi/breaking-params-as-first-arg

Search parameters as first argument

Author: zyc9012

CHANGELOG.md

@@ -10,7 +10,8 @@ and this project adheres to
 
 ### Added
 
-- Expose `EngineName`, `EngineParameters` and `AllowArbitraryParams` types.
+- Expose `EngineParameters` type.
+- Expose `InvalidArgumentTypesError` error.
 
 ### Changed
 

README.md

@@ -25,7 +25,8 @@ npm install serpapi
 
 ```js
 import { getJson } from "serpapi";
-const response = await getJson("google", {
+const response = await getJson({
+  engine: "google",
   api_key: API_KEY, // Get your API_KEY from https://serpapi.com/manage-api-key
   q: "coffee",
   location: "Austin, Texas",
@@ -68,8 +69,8 @@ import { config, getJson } from "serpapi";
 config.api_key = API_KEY;
 config.timeout = 60000;
 
-await getJson("google", { q: "coffee" }); // uses the API key defined in the config
-await getJson("google", { api_key: API_KEY_2, q: "coffee" }); // API_KEY_2 will be used
+await getJson({ engine: "google", q: "coffee" }); // uses the API key defined in the config
+await getJson({ engine: "google", api_key: API_KEY_2, q: "coffee" }); // API_KEY_2 will be used
 ```
 
 ## Pagination
@@ -86,7 +87,7 @@ pagination is not supported for the search engine or there are no more pages to
 be retrieved.
 
 ```js
-const page1 = await getJson("google", { q: "coffee", start: 15 });
+const page1 = await getJson({ engine: "google", q: "coffee", start: 15 });
 const page2 = await page1.next?.();
 ```
 
@@ -134,9 +135,6 @@ Get a JSON response based on search parameters.
 
 #### Parameters
 
-- `engine`
-  **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)**
-  engine name
 - `parameters`
   **[object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)**
   search query parameters for the engine
@@ -146,21 +144,21 @@ Get a JSON response based on search parameters.
 
 ```javascript
 // single call (async/await)
-const json = await getJson("google", { api_key: API_KEY, q: "coffee" });
+const json = await getJson({ engine: "google", api_key: API_KEY, q: "coffee" });
 
 // single call (callback)
-getJson("google", { api_key: API_KEY, q: "coffee" }, console.log);
+getJson({ engine: "google", api_key: API_KEY, q: "coffee" }, console.log);
 ```
 
 ```javascript
 // pagination (async/await)
-const page1 = await getJson("google", { q: "coffee", start: 15 });
+const page1 = await getJson({ engine: "google", q: "coffee", start: 15 });
 const page2 = await page1.next?.();
 ```
 
 ```javascript
 // pagination (callback)
-getJson("google", { q: "coffee", start: 15 }, (page1) => {
+getJson({ engine: "google", q: "coffee", start: 15 }, (page1) => {
   page1.next?.((page2) => {
     console.log(page2);
   });
@@ -170,7 +168,7 @@ getJson("google", { q: "coffee", start: 15 }, (page1) => {
 ```javascript
 // pagination loop (async/await)
 const organicResults = [];
-let page = await getJson("google", { api_key: API_KEY, q: "coffee" });
+let page = await getJson({ engine: "google", api_key: API_KEY, q: "coffee" });
 while (page) {
   organicResults.push(...page.organic_results);
   if (organicResults.length >= 30) break;
@@ -181,7 +179,7 @@ while (page) {
 ```javascript
 // pagination loop (callback)
 const organicResults = [];
-getJson("google", { api_key: API_KEY, q: "coffee" }, (page) => {
+getJson({ engine: "google", api_key: API_KEY, q: "coffee" }, (page) => {
   organicResults.push(...page.organic_results);
   if (organicResults.length < 30 && page.next) {
     page.next();
@@ -198,9 +196,6 @@ Get a HTML response based on search parameters.
 
 #### Parameters
 
-- `engine`
-  **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)**
-  engine name
 - `parameters`
   **[object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)**
   search query parameters for the engine
@@ -210,10 +205,10 @@ Get a HTML response based on search parameters.
 
 ```javascript
 // async/await
-const html = await getHtml("google", { api_key: API_KEY, q: "coffee" });
+const html = await getHtml({ engine: "google", api_key: API_KEY, q: "coffee" });
 
 // callback
-getHtml("google", { api_key: API_KEY, q: "coffee" }, console.log);
+getHtml({ engine: "google", api_key: API_KEY, q: "coffee" }, console.log);
 ```
 
 ### getJsonBySearchId
@@ -245,7 +240,8 @@ Get a JSON response given a search ID.
 #### Examples
 
 ```javascript
-const response = await getJson("google", {
+const response = await getJson({
+  engine: "google",
   api_key: API_KEY,
   async: true,
   q: "coffee",
@@ -290,7 +286,8 @@ Get a HTML response given a search ID.
 #### Examples
 
 ```javascript
-const response = await getJson("google", {
+const response = await getJson({
+  engine: "google",
   api_key: API_KEY,
   async: true,
   q: "coffee",

docs/migrating_from_google_search_results_nodejs.md

@@ -17,7 +17,7 @@ migrate over to the `serpapi` npm package.
 
   // ✅ New way, import and use functions directly.
   import { getJson } from "serpapi";
-  getJson("google", { api_key: API_KEY, ... })
+  getJson({ engine: "google", api_key: API_KEY, ... })
   ```
 
 - The `search_archive` method is replaced by `getJsonBySearchId` and
@@ -63,15 +63,15 @@ migrate over to the `serpapi` npm package.
   engine.json({ q: "coffee", api_key: undefined });
 
   // ✅ Now, no error is thrown when api_key is null
-  getJson("google", { q: "coffee", api_key: null });
+  getJson({ engine: "google", q: "coffee", api_key: null });
   ```
 
 ## Added
 
 - TypeScript types for supported parameters.
 - First-class Promises support.
   ```js
-  const json = await getJson("google", { q: "coffee" });
+  const json = await getJson({ engine: "google", q: "coffee" });
   ```
 - `config` object to configure global `api_key` and `timeout` values.
   ```js
@@ -81,6 +81,6 @@ migrate over to the `serpapi` npm package.
   ```
 - Error classes (`MissingApiKeyError` and `InvalidTimeoutError`).
   ```js
-  getJson("google", { api_key: "" }); // Throws `MissingApiKeyError`
+  getJson({ engine: "google", api_key: "" }); // Throws `MissingApiKeyError`
   getAccount({ api_key: API_KEY, timeout: 0 }); // Throws `InvalidTimeoutError`
   ```

examples/deno/basic_ts/README.md

@@ -20,7 +20,6 @@ deno run example.ts
   following:
   ```ts
   import {
-    AllowArbitraryParams,
     config,
     getJson,
     GoogleParameters,

examples/deno/basic_ts/example.ts

@@ -1,25 +1,21 @@
 import { loadSync } from "https://deno.land/[email protected]/dotenv/mod.ts";
-import {
-  AllowArbitraryParams,
-  config,
-  getJson,
-  GoogleParameters,
-} from "../../../mod.ts";
+import { config, EngineParameters, getJson } from "../../../mod.ts";
 
 const { API_KEY: apiKey } = loadSync();
 const params = {
+  engine: "google",
   q: "Coffee",
   api_key: apiKey,
-} satisfies AllowArbitraryParams<GoogleParameters>;
+} satisfies EngineParameters<"google">;
 
 // Show result as JSON (async/await)
-const response1 = await getJson("google", params);
+const response1 = await getJson(params);
 console.log(response1["organic_results"]);
 
 // Show result as JSON (callback)
-getJson("google", params, (json) => console.log(json["organic_results"]));
+getJson(params, (json) => console.log(json["organic_results"]));
 
 // Use global config
 config.api_key = apiKey;
-const response2 = await getJson("google", { q: "Coffee" });
+const response2 = await getJson({ engine: "google", q: "Coffee" });
 console.log(response2["organic_results"]);

examples/deno/pagination_ts/README.md

@@ -20,7 +20,6 @@ deno run example.ts
   following:
   ```ts
   import {
-    AllowArbitraryParams,
     config,
     getJson,
     GoogleParameters,

examples/deno/pagination_ts/example.ts

@@ -1,23 +1,19 @@
 import { loadSync } from "https://deno.land/[email protected]/dotenv/mod.ts";
-import {
-  AllowArbitraryParams,
-  config,
-  getJson,
-  GoogleParameters,
-} from "../../../mod.ts";
+import { config, EngineParameters, getJson } from "../../../mod.ts";
 
 const { API_KEY: apiKey } = loadSync();
 
 const extractLinks = (results: { link: string }[]) =>
   results.map((r) => r.link);
 
 const params = {
+  engine: "google",
   q: "Coffee",
   api_key: apiKey,
-} satisfies AllowArbitraryParams<GoogleParameters>;
+} satisfies EngineParameters<"google">;
 
 // Pagination (async/await)
-let page1 = await getJson("google", params);
+let page1 = await getJson(params);
 console.log(
   "First page links",
   extractLinks(page1.organic_results),
@@ -29,7 +25,7 @@ console.log(
 );
 
 // Pagination (callback)
-getJson("google", params, (page1) => {
+getJson(params, (page1) => {
   console.log(
     "First page links",
     extractLinks(page1.organic_results),
@@ -44,7 +40,7 @@ getJson("google", params, (page1) => {
 
 // Use global config
 config.api_key = apiKey;
-page1 = await getJson("google", { q: "Coffee" });
+page1 = await getJson({ engine: "google", q: "Coffee" });
 page2 = await page1.next?.();
 console.log(
   "Second page links",
@@ -54,7 +50,7 @@ console.log(
 // Pagination loop (async/await)
 let links: string[] = [];
 let page;
-page = await getJson("google", { q: "Coffee" });
+page = await getJson({ engine: "google", q: "Coffee" });
 while (page) {
   links.push(...extractLinks(page.organic_results));
   if (links.length >= 30) break;
@@ -64,7 +60,7 @@ console.log(links);
 
 // Pagination loop (callback)
 links = [];
-getJson("google", { q: "Coffee" }, (page) => {
+getJson({ engine: "google", q: "Coffee" }, (page) => {
   links.push(...extractLinks(page.organic_results));
   if (links.length < 30 && page.next) {
     page.next();

examples/node/basic_js_commonjs/example.js

@@ -6,20 +6,21 @@ const apiKey = process.env.API_KEY;
 
 const run = async () => {
   const params = {
+    engine: "google",
     q: "Coffee",
     api_key: apiKey,
   };
 
   // Show result as JSON (async/await)
-  const response1 = await getJson("google", params);
+  const response1 = await getJson(params);
   console.log(response1["organic_results"]);
 
   // Show result as JSON (callback)
-  getJson("google", params, (json) => console.log(json["organic_results"]));
+  getJson(params, (json) => console.log(json["organic_results"]));
 
   // Use global config
   config.api_key = apiKey;
-  const response2 = await getJson("google", { q: "Coffee" });
+  const response2 = await getJson({ engine: "google", q: "Coffee" });
   console.log(response2["organic_results"]);
 };
 

examples/node/basic_js_esm/example.js

@@ -5,18 +5,19 @@ Dotenv.config();
 const apiKey = process.env.API_KEY;
 
 const params = {
+  engine: "google",
   q: "Coffee",
   api_key: apiKey,
 };
 
 // Show result as JSON (async/await)
-const response1 = await getJson("google", params);
+const response1 = await getJson(params);
 console.log(response1["organic_results"]);
 
 // Show result as JSON (callback)
-getJson("google", params, (json) => console.log(json["organic_results"]));
+getJson(params, (json) => console.log(json["organic_results"]));
 
 // Use global config
 config.api_key = apiKey;
-const response2 = await getJson("google", { q: "Coffee" });
+const response2 = await getJson({ engine: "google", q: "Coffee" });
 console.log(response2["organic_results"]);

examples/node/basic_ts_esm/example.ts

@@ -1,22 +1,23 @@
 import * as Dotenv from "dotenv";
-import { AllowArbitraryParams, config, getJson, GoogleParameters } from "serpapi";
+import { config, EngineParameters, getJson } from "serpapi";
 
 Dotenv.config();
 const apiKey = process.env.API_KEY;
 
 const params = {
+  engine: "google",
   q: "Coffee",
   api_key: apiKey,
-} satisfies AllowArbitraryParams<GoogleParameters>;
+} satisfies EngineParameters<"google">;
 
 // Show result as JSON (async/await)
-const response1 = await getJson("google", params);
+const response1 = await getJson(params);
 console.log(response1["organic_results"]);
 
 // Show result as JSON (callback)
-getJson("google", params, (json) => console.log(json["organic_results"]));
+getJson(params, (json) => console.log(json["organic_results"]));
 
 // Use global config
 config.api_key = apiKey;
-const response2 = await getJson("google", { q: "Coffee" });
+const response2 = await getJson({ engine: "google", q: "Coffee" });
 console.log(response2["organic_results"]);