{"id":13528273,"url":"https://github.com/intoli/user-agents","last_synced_at":"2025-05-13T19:17:36.964Z","repository":{"id":38849305,"uuid":"143752762","full_name":"intoli/user-agents","owner":"intoli","description":"A JavaScript library for generating random user agents with data that's updated daily.","archived":false,"fork":false,"pushed_at":"2025-05-06T06:52:08.000Z","size":515415,"stargazers_count":1047,"open_issues_count":25,"forks_count":51,"subscribers_count":15,"default_branch":"main","last_synced_at":"2025-05-06T07:55:57.343Z","etag":null,"topics":["browser-automation","browsers","javascript","navigator","random","randomization","user-agent","user-agent-spoofer","web-scraping"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/intoli.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","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,"zenodo":null}},"created_at":"2018-08-06T16:07:45.000Z","updated_at":"2025-05-06T06:52:11.000Z","dependencies_parsed_at":"2023-02-16T16:32:39.107Z","dependency_job_id":"1f448852-8a91-4d61-be4e-b6736709588d","html_url":"https://github.com/intoli/user-agents","commit_stats":{"total_commits":2930,"total_committers":2,"mean_commits":1465.0,"dds":"0.055972696245733755","last_synced_commit":"937979287ad83d8e6c77e6bf2650fe666e7a88c2"},"previous_names":[],"tags_count":2544,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/intoli%2Fuser-agents","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/intoli%2Fuser-agents/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/intoli%2Fuser-agents/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/intoli%2Fuser-agents/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/intoli","download_url":"https://codeload.github.com/intoli/user-agents/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254010830,"owners_count":21999004,"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":["browser-automation","browsers","javascript","navigator","random","randomization","user-agent","user-agent-spoofer","web-scraping"],"created_at":"2024-08-01T06:02:22.924Z","updated_at":"2025-05-13T19:17:36.908Z","avatar_url":"https://github.com/intoli.png","language":"TypeScript","readme":"\u003ch1 vertical-align=\"middle\"\u003e\n    User Agents\n\u003c/h1\u003e\n\n\u003cp align=\"left\"\u003e\n    \u003ca href=\"https://circleci.com/gh/intoli/user-agents/tree/master\"\u003e\n        \u003cimg src=\"https://img.shields.io/circleci/project/github/intoli/user-agents/master.svg\"\n            alt=\"Build Status\"\u003e\u003c/a\u003e\n    \u003ca href=\"https://circleci.com/gh/intoli/user-agents/tree/master\"\u003e\n        \u003cimg src=\"https://img.shields.io/github/last-commit/intoli/user-agents/master.svg\"\n            alt=\"Build Status\"\u003e\u003c/a\u003e\n    \u003ca href=\"https://github.com/intoli/user-agents/blob/master/LICENSE\"\u003e\n        \u003cimg src=\"https://img.shields.io/badge/License-BSD%202--Clause-blue.svg\"\n            alt=\"License\"\u003e\u003c/a\u003e\n    \u003ca href=\"https://www.npmjs.com/package/user-agents\"\u003e\n        \u003cimg src=\"https://img.shields.io/npm/v/user-agents.svg\"\n            alt=\"NPM Version\"\u003e\u003c/a\u003e\n    \u003cspan\u003e\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u003c/span\u003e\n    \u003ca target=\"_blank\" href=\"https://twitter.com/home?status=User%20Agents%20is%20a%20JavaScript%20module%20for%20generating%20random%20user%20agents%20that's%20updated%20daily%20with%20new%20market%20share%20data.%0A%0Ahttps%3A//github.com/intoli/user-agents\"\u003e\n        \u003cimg height=\"26px\" src=\"https://simplesharebuttons.com/images/somacro/twitter.png\"\n            alt=\"Tweet\"\u003e\u003c/a\u003e\n    \u003ca target=\"_blank\" href=\"https://www.facebook.com/sharer/sharer.php?u=https%3A//github.com/intoli/user-agents\"\u003e\n        \u003cimg height=\"26px\" src=\"https://simplesharebuttons.com/images/somacro/facebook.png\"\n            alt=\"Share on Facebook\"\u003e\u003c/a\u003e\n    \u003ca target=\"_blank\" href=\"http://reddit.com/submit?url=https%3A%2F%2Fgithub.com%2Fintoli%2Fuser-agents\u0026title=User%20Agents%20-%20Random%20user%20agent%20generation%20with%20daily-updated%20market%20share%20data\"\u003e\n        \u003cimg height=\"26px\" src=\"https://simplesharebuttons.com/images/somacro/reddit.png\"\n            alt=\"Share on Reddit\"\u003e\u003c/a\u003e\n    \u003ca target=\"_blank\" href=\"https://news.ycombinator.com/submitlink?u=https://github.com/intoli/user-agents\u0026t=User%20Agents%20-%20Random%20user%20agent%20generation%20with%20daily-updated%20market%20share%20data\"\u003e\n        \u003cimg height=\"26px\" src=\"media/ycombinator.png\"\n            alt=\"Share on Hacker News\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n\n###### [Installation](#installation) | [Examples](#examples) | [API](#api) | [How it Works](https://intoli.com/blog/user-agents/) | [Contributing](#contributing)\n\n\u003e User-Agents is a JavaScript package for generating random [User Agents](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/User-Agent) based on how frequently they're used in the wild.\n\u003e A new version of the package is automatically released every day, so the data is always up to date.\n\u003e The generated data includes hard to find browser-fingerprint properties, and powerful filtering capabilities allow you to restrict the generated user agents to fit your exact needs.\n\nWeb scraping often involves creating realistic traffic patterns, and doing so generally requires a good source of data.\nThe User-Agents package provides a comprehensive dataset of real-world user agents and other browser properties which are commonly used for browser fingerprinting and blocking automated web browsers.\nUnlike other random user agent generation libraries, the User-Agents package is updated automatically on a daily basis.\nThis means that you can use it without worrying about whether the data will be stale in a matter of months.\n\nGenerating a realistic random user agent is as simple as running `new UserAgent()`, but you can also easily generate user agents which correspond to a specific platform, device category, or even operating system version.\nThe fastest way to get started is to hop down to the [Examples](#examples) section where you can see it in action!\n\n\n## Installation\n\nThe User Agents package is available on npm with the package name [user-agents](https://npmjs.com/package/user-agents).\nYou can install it using your favorite JavaScript package manager in the usual way.\n\n```bash\n# With npm: npm install user-agents\n# With pnpm: pnpm install user-agents\n# With yarn:\nyarn add user-agents\n```\n\n\n## Examples\n\nThe User-Agents library offers a very flexible interface for generating user agents.\nThese examples illustrate some common use cases, and show how the filtering API can be used in practice.\n\n\n### Generating a Random User Agent\n\nThe most basic usage involves simply instantiating a `UserAgent` instance.\nIt will be automatically populated with a random user agent and browser fingerprint.\n\n\n```javascript\nimport UserAgent from 'user-agents';\n\n\nconst userAgent = new UserAgent();\nconsole.log(userAgent.toString());\nconsole.log(JSON.stringify(userAgent.data, null, 2));\n```\n\nIn this example, we've generated a random user agent and then logged out stringified versions both the `userAgent.data` object and `userAgent` itself to the console.\nAn example output might look something like this.\n\n```literal\nMozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/68.0.3440.106 Safari/537.36\n```\n\n```json\n{\n  \"appName\": \"Netscape\",\n  \"connection\": {\n    \"downlink\": 10,\n    \"effectiveType\": \"4g\",\n    \"rtt\": 0\n  },\n  \"platform\": \"Win32\",\n  \"pluginsLength\": 3,\n  \"vendor\": \"Google Inc.\",\n  \"userAgent\": \"Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/68.0.3440.106 Safari/537.36\",\n  \"viewportHeight\": 660,\n  \"viewportWidth\": 1260,\n  \"deviceCategory\": \"desktop\",\n  \"screenHeight\": 800,\n  \"screenWidth\": 1280\n}\n```\n\nThe `userAgent.toString()` call converts the user agent into a string which corresponds to the actual user agent.\nThe `data` property includes a randomly generated browser fingerprint that can be used for more detailed emulation.\n\n\n### Restricting Device Categories\n\nBy passing an object as a filter, each corresponding user agent property will be restricted based on its values.\n\n```javascript\nimport UserAgent from 'user-agents';\n\nconst userAgent = new UserAgent({ deviceCategory: 'mobile' })\n```\n\nThis code will generate a user agent with a `deviceCategory` of `mobile`.\nIf you replace `mobile` with either `desktop` or `tablet`, then the user agent will correspond to one of those device types instead.\n\n\n### Generating Multiple User Agents With The Same Filters\n\nThere is some computational overhead involved with applying a set of filters, so it's far more efficient to reuse the filter initialization when you need to generate many user agents with the same configuration.\nYou can call any initialized `UserAgent` instance like a function, and it will generate a new random instance with the same filters (you can also call `userAgent.random()` if you're not a fan of the shorthand).\n\n```javascript\nimport UserAgent from 'user-agents';\n\nconst userAgent = new UserAgent({ platform: 'Win32' });\nconst userAgents = Array(1000).fill().map(() =\u003e userAgent());\n```\n\nThis code example initializes a single user agent with a filter that limits the platform to `Win32`, and then uses that instance to generate 1000 more user agents with the same filter.\n\n\n### Regular Expression Matching\n\nYou can pass a regular expression as a filter and the generated user agent will be guaranteed to match that regular expression.\n\n```javascript\nimport UserAgent from 'user-agents';\n\nconst userAgent = new UserAgent(/Safari/);\n```\n\nThis example will generate a user agent that contains a `Safari` substring.\n\n\n### Custom Filter Functions\n\nIt's also possible to implement completely custom logic by using a filter as a function.\nThe raw `userAgent.data` object will be passed into your function, and it will be included as a possible candidate only if your function returns `true`.\nIn this example, we'll use the [useragent](https://www.npmjs.com/package/useragent) package to parse the user agent string and then restrict the generated user agents to iOS devices with an operating system version of 11 or greater.\n\n```javascript\nimport UserAgent from 'user-agents';\nimport { parse } from 'useragent';\n\nconst userAgent = new UserAgent((data) =\u003e {\n  const os = parse(data.userAgent).os;\n  return os.family === 'iOS' \u0026\u0026 parseInt(os.major, 10) \u003e 11;\n});\n```\n\nThe filtering that you apply here is completely up to you, so there's really no limit to how specific it can be.\n\n\n### Combining Filters With Arrays\n\nYou can also use arrays to specify collections of filters that will all be applied.\nThis example combines a regular expression filter with an object filter to generate a user agent with a connection type of `wifi`, a platform of `MacIntel`, and a user agent that includes a `Safari` substring.\n\n```javascript\nimport UserAgent from 'user-agents';\n\nconst userAgent = new UserAgent([\n  /Safari/,\n  {\n    connection: {\n      type: 'wifi',\n    },\n    platform: 'MacIntel',\n  },\n]);\n```\n\nThis example also shows that you can specify both multiple and nested properties on object filters.\n\n\n## API\n\n### class: UserAgent([filters])\n\n- `filters` \u003c`Array`, `Function`, `Object`, `RegExp`, or `String`\u003e - A set of filters to apply to the generated user agents.\n    The filter specification is extremely flexible, and reading through the [Examples](#examples) section is the best way to familiarize yourself with what sort of filtering is possible.\n\n`UserAgent` is an object that contains the details of a randomly generated user agent and corresponding browser fingerprint.\nEach time the class is instantiated, it will randomly populate the instance with a new user agent based on the specified filters.\nThe instantiated class can be cast to a user agent string by explicitly calling `toString()`, accessing the `userAgent` property, or implicitly converting the type to a primitive or string in the standard JavaScript ways (*e.g.* `` `${userAgent}` ``).\nOther properties can be accessed as outlined below.\n\n\n#### userAgent.random()\n\n- returns: \u003c`UserAgent`\u003e\n\nThis method generates a new `UserAgent` instance using the same filters that were used to construct `userAgent`.\nThe following examples both generate two user agents based on the same filters.\n\n```javascript\n// Explicitly use the constructor twice.\nconst firstUserAgent = new UserAgent(filters);\nconst secondUserAgent = new UserAgent(filters);\n```\n\n```javascript\n// Use the `random()` method to construct a second user agent.\nconst firstUserAgent = new UserAgent(filters);\nconst secondUserAgent = firstUserAgent.random();\n```\n\nThe reason to prefer the second pattern is that it reuses the filter processing and preparation of the data for random selection.\nSubsequent random generations can easily be over 100x faster than the initial construction.\n\n\n#### userAgent()\n\n- returns: \u003c`UserAgent`\u003e\n\nAs a bit of syntactic sugar, you can call a `UserAgent` instance like `userAgent()` as a shorthand for `userAgent.random()`.\nThis allows you to think of the instance as a generator, and lends itself to writing code like this.\n\n```javascript\nconst generateUserAgent = new UserAgent(filters);\nconst userAgents = Array(100).fill().map(() =\u003e generateUserAgent());\n```\n\n#### userAgent.toString()\n\n- returns: \u003c`String`\u003e\n\nCasts the `UserAgent` instance to a string which corresponds to the user agent header.\nEquivalent to accessing the `userAgent.userAgent` property.\n\n\n#### userAgent.data\n\n- returns: \u003c`Object`\u003e\n    - `appName` \u003c`String`\u003e - The value of [navigator.appName](https://developer.mozilla.org/en-US/docs/Web/API/NavigatorID/appName).\n    - `connection` \u003c`Object`\u003e - The value of [navigator.connection](https://developer.mozilla.org/en-US/docs/Web/API/Navigator/connection).\n    - `cpuClass` \u003c`String`\u003e - The value of [navigator.cpuClass](https://msdn.microsoft.com/en-us/library/ms531090\\(v=vs.85\\).aspx).\n    - `deviceCategory` \u003c`String`\u003e - One of `desktop`, `mobile`, or `tablet` depending on the type of device.\n    - `oscpu` \u003c`String`\u003e - The value of [navigator.oscpu](https://developer.mozilla.org/en-US/docs/Web/API/Navigator/oscpu).\n    - `platform` \u003c`String`\u003e - The value of [navigator.platform](https://developer.mozilla.org/en-US/docs/Web/API/NavigatorID/platform).\n    - `pluginsLength` \u003c`Number`\u003e - The value of [navigator.plugins.length](https://developer.mozilla.org/en-US/docs/Web/API/NavigatorPlugins/plugins).\n    - `screenHeight` \u003c`Number`\u003e - The value of [screen.height](https://developer.mozilla.org/en-US/docs/Web/API/Screen/height).\n    - `screenWidth` \u003c`Number`\u003e - The value of [screen.width](https://developer.mozilla.org/en-US/docs/Web/API/Screen/width).\n    - `vendor` \u003c`String`\u003e - The value of [navigator.vendor](https://developer.mozilla.org/en-US/docs/Web/API/Navigator/vendor).\n    - `userAgent` \u003c`String`\u003e - The value of [navigator.userAgent](https://developer.mozilla.org/en-US/docs/Web/API/NavigatorID/userAgent).\n    - `viewportHeight` \u003c`Number`\u003e - The value of [window.innerHeight](https://developer.mozilla.org/en-US/docs/Web/API/Window/innerHeight).\n    - `viewportWidth` \u003c`Number`\u003e - The value of [window.innerWidth](https://developer.mozilla.org/en-US/docs/Web/API/Window/innerWidth).\n\nThe `userAgent.data` contains the randomly generated fingerprint for the `UserAgent` instance.\nNote that each property of `data` is also accessible directly on `userAgent`.\nFor example, `userAgent.appName` is equivalent to `userAgent.data.appName`.\n\n\n## Versioning\n\nThe project follows [the Semantic Versioning guidelines](https://semver.org/).\nThe automated deployments will always correspond to patch versions, and minor versions should not introduce breaking changes.\nIt's likely that the structure of user agent data will change in the future, and this will correspond to a new major version.\n\nPlease keep in mind that older major versions will cease to be updated after a new major version is released.\nYou can continue to use older versions of the software, but you'll need to upgrade to get access to the latest data.\n\n\n## Acknowledgements\n\nThe user agent frequency data used in this library is generously provided by [Intoli](https://intoli.com), the premier residential and smart proxy provider for web scraping.\nThe details of how the data is updated can be found in the blog post [User-Agents — A random user agent generation library that's always up to date](https://intoli.com/blog/user-agents/).\n\nIf you have a high-traffic website and would like to contribute data to the project, then send us an email at [contact@intoli.com](mailto:contact@intoli.com).\nAdditional data sources will help make the library more useful, and we'll be happy to add a link to your site in the acknowledgements.\n\n\n## Contributing\n\nContributions are welcome, but please follow these contributor guidelines outlined in [CONTRIBUTING.md](CONTRIBUTING.md).\n\n\n## License\n\nUser-Agents is licensed under a [BSD 2-Clause License](LICENSE) and is copyright [Intoli, LLC](https://intoli.com).\n","funding_links":[],"categories":["TypeScript","\u003ca name=\"utils--user-agents\"\u003e\u003c/a\u003e🧰 Utils \u0026 User Agents"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fintoli%2Fuser-agents","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fintoli%2Fuser-agents","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fintoli%2Fuser-agents/lists"}