123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245import { AccountApiParams, AccountInformation, BaseParameters, BaseResponse, EngineMap, GetBySearchIdParameters, Locations, LocationsApiParams,} from "./types.ts";import { _internals, execute, validateApiKey, validateTimeout,} from "./utils.ts";
const ACCOUNT_PATH = "/account";const LOCATIONS_PATH = "/locations.json";const SEARCH_PATH = "/search";const SEARCH_ARCHIVE_PATH = `/searches`;
/** * Get a JSON response based on search parameters. * - Accepts an optional callback. * * @param {string} engine - engine name * @param {object} parameters - search query parameters for the engine * @param {fn=} callback - optional callback * @example * // async/await * const json = await getJson("google", { api_key: API_KEY, q: "coffee" }); * * // callback * getJson("google", { api_key: API_KEY, q: "coffee" }, console.log); */export async function getJson< E extends keyof EngineMap, R extends BaseResponse<EngineMap[E]["parameters"]>,>( engine: E, parameters: BaseParameters & EngineMap[E]["parameters"], callback?: (json: R) => void,) { const key = validateApiKey(parameters.api_key, true); const timeout = validateTimeout(parameters.timeout); const response = await _internals.execute( SEARCH_PATH, { ...parameters, engine, api_key: key, output: "json", }, timeout, ); const json = await response.json() as R; callback?.(json); return json;}
/** * Get a HTML response based on search parameters. * - Accepts an optional callback. * - Responds with a JSON string if the search request hasn't completed. * * @param {string} engine - engine name * @param {object} parameters - search query parameters for the engine * @param {fn=} callback - optional callback * @example * // async/await * const html = await getHtml("google", { api_key: API_KEY, q: "coffee" }); * * // callback * getHtml("google", { api_key: API_KEY, q: "coffee" }, console.log); */export async function getHtml<E extends keyof EngineMap>( engine: E, parameters: BaseParameters & EngineMap[E]["parameters"], callback?: (html: string) => void,) { const key = validateApiKey(parameters.api_key, true); const timeout = validateTimeout(parameters.timeout); const response = await _internals.execute( SEARCH_PATH, { ...parameters, engine, api_key: key, output: "html", }, timeout, ); const html = await response.text(); callback?.(html); return html;}
/** * Get a JSON response given a search ID. * - This search ID can be obtained from the `search_metadata.id` key in the response. * - Typically used together with the `async` parameter. * - Accepts an optional callback. * * @param {string} searchId - search ID * @param {object} parameters * @param {string=} [parameters.api_key] - API key * @param {number=} [parameters.timeout] - timeout in milliseconds * @param {fn=} callback - optional callback * @example * const response = await getJson("google", { api_key: API_KEY, async: true, q: "coffee" }); * const { id } = response.search_metadata; * await delay(1000); // wait for the request to be processed. * * // async/await * const json = await getJsonBySearchId(id, { api_key: API_KEY }); * * // callback * getJsonBySearchId(id, { api_key: API_KEY }, console.log); */export async function getJsonBySearchId< R extends BaseResponse,>( searchId: string, parameters: GetBySearchIdParameters = {}, callback?: (json: R) => void,) { const key = validateApiKey(parameters.api_key); const timeout = validateTimeout(parameters.timeout); const response = await _internals.execute( `${SEARCH_ARCHIVE_PATH}/${searchId}`, { api_key: key, output: "json", }, timeout, ); const json = await response.json() as R; callback?.(json); return json;}
/** * Get a HTML response given a search ID. * - This search ID can be obtained from the `search_metadata.id` key in the response. * - Typically used together with the `async` parameter. * - Accepts an optional callback. * - Responds with a JSON if the search request hasn't completed. * * @param {string} searchId - search ID * @param {object} parameters * @param {string=} [parameters.api_key] - API key * @param {number=} [parameters.timeout] - timeout in milliseconds * @param {fn=} callback - optional callback * @example * const response = await getJson("google", { api_key: API_KEY, async: true, q: "coffee" }); * const { id } = response.search_metadata; * await delay(1000); // wait for the request to be processed. * * // async/await * const html = await getHtmlBySearchId(id, { api_key: API_KEY }); * * // callback * getHtmlBySearchId(id, { api_key: API_KEY }, console.log); */export async function getHtmlBySearchId( searchId: string, parameters: GetBySearchIdParameters = {}, callback?: (html: string) => void,) { const key = validateApiKey(parameters.api_key); const timeout = validateTimeout(parameters.timeout); const response = await _internals.execute( `${SEARCH_ARCHIVE_PATH}/${searchId}`, { api_key: key, output: "html", }, timeout, ); const html = await response.text(); callback?.(html); return html;}
/** * Get account information of an API key. * https://serpapi.com/account-api * * @param {object} parameters * @param {string=} [parameters.api_key] - API key * @param {number=} [parameters.timeout] - timeout in milliseconds * @param {fn=} callback - optional callback * @example * // async/await * const info = await getAccount({ api_key: API_KEY }); * * // callback * getAccount({ api_key: API_KEY }, console.log); */export async function getAccount( parameters: AccountApiParams = {}, callback?: (info: AccountInformation) => void,) { const key = validateApiKey(parameters.api_key); const timeout = validateTimeout(parameters.timeout); const response = await execute(ACCOUNT_PATH, { api_key: key, }, timeout); const info = await response.json() as AccountInformation; callback?.(info); return info;}
/** * Get supported locations. Does not require an API key. * https://serpapi.com/locations-api * * @param {object} parameters * @param {string=} [parameters.q] - query for a location * @param {number=} [parameters.limit] - limit on number of locations returned * @param {number=} [parameters.timeout] - timeout in milliseconds * @param {fn=} callback - optional callback * @example * // async/await * const locations = await getLocations({ limit: 3 }); * * // callback * getLocations({ limit: 3 }, console.log); */export async function getLocations( parameters: LocationsApiParams = {}, callback?: (locations: Locations) => void,) { const timeout = validateTimeout(parameters.timeout); const response = await execute( LOCATIONS_PATH, parameters, timeout, ); const locations = await response.json() as Locations; callback?.(locations); return locations;}