feat: typed Google 搜索 parameters and responses (fixes #33) - #37
Conversation
Replace Record<string, any> with Google搜索Parameters and Google搜索Response for the Google engine. Adds a typed overload to getJson() so users get autocomplete and validation when passing engine: "google". Generic types preserved for backwards compatibility. Pattern is extensible to other engines (Bing, YouTube, etc.) by adding files under src/engines/. Fixes serpapi#33
There was a problem hiding this comment.
Pull request overview
Introduces engine-specific TypeScript typings for SerpApi’s Google 搜索, and wires those types into the public API so Google searches can have autocompleted parameters and typed JSON responses.
Changes:
- Added Google 搜索 engine parameter/response interfaces under
src/engines/google.tsand re-exported them viasrc/types.ts. - Added a typed overload for
getJson()when called withGoogle搜索Parameters. - Added a new test file intended to validate compile-time behavior of the new types.
Reviewed changes
Copilot reviewed 5 out of 5 changed files in this pull request and generated 3 comments.
Show a summary per file
| File | Description |
|---|---|
src/engines/google.ts |
Adds Google 搜索 request/response type definitions. |
src/types.ts |
Re-exports Google engine-specific types from the new engine module. |
src/serpapi.ts |
Adds getJson() overload to provide typed Google 搜索 responses. |
mod.ts |
Re-exports new Google-related types from the package entrypoint. |
tests/types_test.ts |
Adds tests intended to validate engine-specific typing behavior. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| Google搜索Response, | ||
| OrganicResult, | ||
| } from "../src/types.ts"; | ||
| import { getJson } from "../src/serpapi.ts"; |
There was a problem hiding this comment.
getJson is imported but I don't see it being used for any tests - could we remove if not needed
| device?: "desktop" | "tablet" | "mobile"; | ||
| no_cache?: boolean; | ||
| async?: boolean; | ||
|
|
There was a problem hiding this comment.
I'm wondering if we should extract out SerpApi Parameters and have the other engines' types extend it since nearly every other engine has the same SerpApi-specific params:https://serpapi.com/search-api#api-parameters-serpapi-parameters
What do you think @zyc9012
There was a problem hiding this comment.
This library used to have types, but we removed them (#15) because all the parameters are unstable. We can add new engines/parameters from time to time, which makes it hard to sync with SDKs. I'm not sure if we want to bring types back.
Summary
Google搜索ParametersandGoogle搜索Responsetyped interfaces matching the Google 搜索 API docsgetJson()— when you passengine: "google", you get autocomplete and typed responsesEngineParametersandBaseResponsepreserved for backwards compatibility with all other enginesOrganicResult,KnowledgeGraph,RelatedQuestion,搜索Metadata,搜索Information, and搜索ParametersContext
This is a starting point for addressing #33. The current types (
EngineParameters = Record<string, any>) provide no autocomplete, no typo protection, and no response typing. As the issue notes, this is effectively the same as not having TypeScript support.Typing every engine at once felt too large for a single PR. Instead, this PR is meant to be a pattern that can be incrementally applied to other engines.
Approach
Each engine gets its own file under
src/engines/. Adding Bing, YouTube, Amazon, etc. follows the same pattern: one file per engine, one typed overload per function.The index signature
[key: string]: unknownon the response type ensures new API fields work without SDK updates. This was a design decision that could be re-evaluated depending on desired maintenance burden for the SDK.