{"id":20537050,"url":"https://github.com/zenrows/zenrows-node-sdk","last_synced_at":"2025-04-14T07:22:15.544Z","repository":{"id":57405513,"uuid":"404391272","full_name":"ZenRows/zenrows-node-sdk","owner":"ZenRows","description":"SDK to access ZenRows API directly from Node.js. We handle proxies rotation, headless browsers and CAPTCHAs for you.","archived":false,"fork":false,"pushed_at":"2024-09-09T10:41:45.000Z","size":289,"stargazers_count":14,"open_issues_count":5,"forks_count":3,"subscribers_count":4,"default_branch":"main","last_synced_at":"2024-10-29T23:07:50.602Z","etag":null,"topics":["javascript","nodejs","proxies","proxy","rotating-proxy","scraper","scraping","sdk","sdk-js","webscraping"],"latest_commit_sha":null,"homepage":"https://www.zenrows.com/","language":"TypeScript","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/ZenRows.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,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-09-08T15:02:56.000Z","updated_at":"2024-10-26T07:11:59.000Z","dependencies_parsed_at":"2023-01-23T16:16:20.512Z","dependency_job_id":"17980f54-192b-4e79-8daa-17ebc7b3f8d4","html_url":"https://github.com/ZenRows/zenrows-node-sdk","commit_stats":{"total_commits":19,"total_committers":2,"mean_commits":9.5,"dds":"0.052631578947368474","last_synced_commit":"a12a1d4755777a3080043c776fccc0dfec286e83"},"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ZenRows%2Fzenrows-node-sdk","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ZenRows%2Fzenrows-node-sdk/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ZenRows%2Fzenrows-node-sdk/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ZenRows%2Fzenrows-node-sdk/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ZenRows","download_url":"https://codeload.github.com/ZenRows/zenrows-node-sdk/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248837290,"owners_count":21169401,"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":["javascript","nodejs","proxies","proxy","rotating-proxy","scraper","scraping","sdk","sdk-js","webscraping"],"created_at":"2024-11-16T00:38:45.205Z","updated_at":"2025-04-14T07:22:15.513Z","avatar_url":"https://github.com/ZenRows.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ZenRows Node.js SDK\n\nSDK to access [ZenRows](https://www.zenrows.com/) API directly from Node.js. ZenRows handles proxies rotation, headless browsers, and CAPTCHAs for you.\n\n## Installation\n\nInstall the SDK with your package manager of choice.\n\n```bash\nnpm install zenrows\nyarn add zenrows\npnpm install zenrows\nbun install zenrows\n```\n\n## Usage\n\nStart using the API by [creating your API Key](https://app.zenrows.com/register?p=free).\n\nThe SDK uses the official [fetch api](https://nodejs.org/dist/latest-v18.x/docs/api/globals.html) for HTTP requests. The client's response will be a [`Response`](https://nodejs.org/dist/latest-v18.x/docs/api/globals.html#response).\n\nIt also uses [fetch-retry](https://github.com/jonbern/fetch-retry) to automatically retry failed requests (status code 429 and 5XX). Retries are not active by default; you need to specify the number of retries, as shown below. It already includes an exponential back-off retry delay between failed requests.\n\n```javascript\nconst { ZenRows } = require(\"zenrows\");\n\nconst apiKey = \"YOUR-API-KEY\";\nconst url = \"https://www.zenrows.com/\";\n\n(async () =\u003e {\n  const client = new ZenRows(apiKey, { retries: 1 });\n\n  const response = await client.get(\n    url,\n    {\n      // Our algorithm allows to automatically extract content from any website\n      autoparse: false,\n\n      // CSS Selectors for data extraction (i.e. {\"links\":\"a @href\"} to get href attributes from links)\n      css_extractor: \"\",\n\n      // Enable Javascript with a headless browser (5 credits)\n      js_render: false,\n\n      // Use residential proxies (10 credits)\n      premium_proxy: false,\n\n      // Make your request from a given country. Requires premium_proxy\n      proxy_country: \"\",\n\n      // Wait for a given CSS Selector to load in the DOM. Requires js_render\n      wait_for: \".content\",\n\n      // Wait a fixed amount of time in milliseconds. Requires js_render\n      wait: 2500,\n\n      // Block specific resources from loading, check docs for the full list. Requires js_render\n      block_resources: \"image,media,font\",\n\n      // Change the browser's window width and height. Requires js_render\n      window_width: 1920,\n      window_height: 1080,\n\n      // Will automatically use either desktop or mobile user agents in the headers\n      device: \"desktop\",\n\n      // Will return the status code returned by the website\n      original_status: false,\n    },\n    {\n      headers: {\n        Referrer: \"https://www.google.com\",\n        \"User-Agent\": \"MyCustomUserAgent\",\n      },\n    }\n  );\n\n  // You can also use response.json() if you're expecting JSON data.\n  const data = await response.text();\n\n  console.log(data);\n\n  /* \u003c!doctype html\u003e \u003chtml... */\n\n  // With the CSS selector {\"links\":\"a @href\"}\n  /*\n        {\n            links: [\n                'https://www.zenrows.com',\n                'https://www.zenrows.com/blog',\n                ...\n            ]\n        }\n    */\n})();\n```\n\nYou can also pass optional parameters and headers; the list above is a reference. For more info, check out [the documentation page](https://www.zenrows.com/documentation).\n\nSending headers to the target URL will overwrite our defaults. Be careful when doing it and contact us if there is any problem.\n\n### POST Requests\n\nThe SDK also offers POST requests by calling the `client.post` method. It can receive a new parameter `data` that represents the data sent in, for example, a form.\n\n```javascript\nconst { ZenRows } = require(\"zenrows\");\n\nconst apiKey = \"YOUR-API-KEY\";\nconst url = \"https://httpbin.org/anything\";\n\n(async () =\u003e {\n  const client = new ZenRows(apiKey, { retries: 1 });\n\n  const response = await client.post(\n    url,\n    {\n      // The same params as in GET requests\n    },\n    {\n      data: new URLSearchParams({\n        key1: \"value1\",\n        key2: \"value2\",\n      }).toString(),\n    }\n  );\n\n  const data = await response.json();\n\n  console.log(data);\n  /*\n        ...\n        form: { key1: 'value1', key2: 'value2' },\n        ...\n    */\n})();\n```\n\n### Concurrency\n\nTo limit the concurrency, it uses [fastq](https://github.com/mcollina/fastq), which will simultaneously send a maximum of requests. The concurrency is determined by the plan you are in, so take a look at the [pricing](https://www.zenrows.com/pricing) and set it accordingly. Take into account that each client instance will have its own limit, meaning that two different scripts will not share it, and 429 (Too Many Requests) errors might arise.\n\nWe use [`Promise.allSettled()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise/allSettled) in the example below, available from Node 12.9. It will wait for all the promises to finish, and the results are objects with a status marking them as fulfilled or rejected. The main difference with `Promise.all()` is that it won't fail if any requests fail. It might make your scraping more robust since the whole list of URLs will run, even if some of them fail.\n\n```javascript\nconst { ZenRows } = require(\"zenrows\");\n\nconst apiKey = \"YOUR-API-KEY\";\n\n(async () =\u003e {\n  const client = new ZenRows(apiKey, { concurrency: 5, retries: 1 });\n\n  const urls = [\n    \"https://www.zenrows.com/\",\n    // ...\n  ];\n\n  const promises = urls.map((url) =\u003e client.get(url));\n\n  const results = await Promise.allSettled(promises);\n  console.log(results);\n  /*\n    [\n        {\n            status: 'fulfilled',\n            value: {\n                status: 200,\n                statusText: 'OK',\n                data: `\u003c!doctype html\u003e \u003chtml lang=\"en\"\u003e \u003chead\u003e ...\n            \n        ...\n    */\n\n  // separate results list into rejected and fulfilled for later processing\n  const rejected = results.filter(({ status }) =\u003e status === \"rejected\");\n  const fulfilled = results.filter(({ status }) =\u003e status === \"fulfilled\");\n})();\n```\n\n#### An important note about Promise.allSettled() on TypeScript\n\n`Promise.allSettled()` does not narrow the type of the array elements in the callback function. This means that you will need to cast the type of the array elements to `PromiseSettledResult\u003cResponse\u003e` to access the `status` and `value` properties.\n\n```typescript\nconst promises = urls.map((url) =\u003e client.get(url));\n\nconst results = await Promise.allSettled(promises);\n\nconst fulfilled = results\n  .filter(\n    (item): item is PromiseFulfilledResult\u003cResponse\u003e =\u003e\n      item.status === \"fulfilled\"\n  )\n  .map((item) =\u003e item.value.json());\n```\n\n## Examples\n\nTake a look at the [examples directory](./examples) for Javascript and TypeScript files using the SDK.\nIt has its own package.json file and includes `zenrows` SDK ready to use.\nEach file makes two requests, the first with CSS selectors and the second with CSS selectors and premium proxies in the US.\n\n```bash\ncd examples\nnpm install\nnode index.js # JS example\nnpx tsx index.ts # TS example\n```\n\n## Contributing\n\nPull requests are welcome. For significant changes, please open an issue first to discuss what you would like to change.\n\n## License\n\n[MIT](./LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzenrows%2Fzenrows-node-sdk","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fzenrows%2Fzenrows-node-sdk","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzenrows%2Fzenrows-node-sdk/lists"}