{"id":15289023,"url":"https://github.com/handcraftedbits/netshot","last_synced_at":"2026-01-04T18:40:28.349Z","repository":{"id":57310357,"uuid":"83842003","full_name":"handcraftedbits/netshot","owner":"handcraftedbits","description":"A simple REST service for taking web page screenshots via Electroshot","archived":false,"fork":false,"pushed_at":"2017-10-18T07:24:03.000Z","size":24,"stargazers_count":1,"open_issues_count":2,"forks_count":2,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-03-01T15:04:48.932Z","etag":null,"topics":["electron","nodejs","rest","screenshot"],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/handcraftedbits.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}},"created_at":"2017-03-03T21:16:09.000Z","updated_at":"2017-03-26T18:27:51.000Z","dependencies_parsed_at":"2022-09-03T13:24:46.435Z","dependency_job_id":null,"html_url":"https://github.com/handcraftedbits/netshot","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/handcraftedbits%2Fnetshot","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/handcraftedbits%2Fnetshot/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/handcraftedbits%2Fnetshot/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/handcraftedbits%2Fnetshot/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/handcraftedbits","download_url":"https://codeload.github.com/handcraftedbits/netshot/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245217791,"owners_count":20579297,"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":["electron","nodejs","rest","screenshot"],"created_at":"2024-09-30T15:56:37.590Z","updated_at":"2026-01-04T18:40:28.314Z","avatar_url":"https://github.com/handcraftedbits.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Netshot [![npm](https://img.shields.io/npm/v/netshot.svg)](https://www.npmjs.com/package/netshot) [![Build Status](https://travis-ci.org/handcraftedbits/netshot.svg?branch=master)](https://travis-ci.org/handcraftedbits/netshot) [![Coverage Status](https://coveralls.io/repos/github/handcraftedbits/netshot/badge.svg)](https://coveralls.io/github/handcraftedbits/netshot)\n\nA simple REST service for taking web page screenshots via [Electroshot](https://github.com/mixu/electroshot).\n\n# Features\n\n* Based on [Electron](https://electron.atom.io) so you get a recent version of\n  [Chromium](https://www.chromium.org/Home) for web page rendering, including:\n  * Webfonts\n  * CSS and JavaScript injection\n  * Device emulation\n  * Network emulation\n  * And more...\n* A simple REST API for creating, retrieving, and deleting screenshots\n\n# Usage\n\n## Prerequisites\n\n### Linux\n\nYou should make sure your Linux installation has a complete X11 distribution.  You may also want to install the\n[Microsoft TrueType core fonts](https://en.wikipedia.org/wiki/Core_fonts_for_the_Web) as many web pages rely on these\nfonts (or equivalents).\n\n#### Headless Usage\n\nWhen running netshot in a headless manner, you will also need to install\n[Xvfb](https://www.x.org/archive/X11R7.6/doc/man/man1/Xvfb.1.xhtml) to provide an in-memory display for Electron.\n\nOn [Ubuntu](https://www.ubuntu.com) systems, the following command can be used to install the minimum set of\ndependencies required to run netshot in a headless manner:\n\n```bash\napt-get install libasound2 libgconf-2-4 libgtk2.0-0 libnss3 libxss1 libxtst6 ttf-mscorefonts-installer xvfb\n```\n\nIf you are not using Ubuntu, consult your distribution's package repository for equivalent packages.\n\n## Installation\n\nMake sure you have [Node.js](https://nodejs.org) installed and then install netshot with `npm`:\n\n```bash\nnpm install -g netshot\n```\n\n## Starting the netshot Server\n\nThe netshot server can be started by running\n\n```bash\nnetshot -d \u003cdirectory\u003e -p \u003cport\u003e\n```\n\nWhere `\u003cdirectory\u003e` is the directory where screenshots will be saved and `\u003cport\u003e` is the port used to listen for\nincoming connections.  If `-d` is not specified, `\u003cdirectory\u003e` will default to `%TEMP%\\__netshot` on Windows (or\n`/tmp/__netshot` on all other platforms).  If `-p` is not specified, `\u003cport\u003e` will default to `8000`.\n\n### Headless Usage\n\nWhen running netshot in a headless manner, you must also create a virtual framebuffer for Electroshot.  The recommended\nway to do this is to start netshot with `xvfb-run`:\n\n```bash\nxvfb-run --server-args \"-screen 0 640x480x24\" netshot\n```\n\n### Docker Image\n\nA [Docker image](https://hub.docker.com/r/handcraftedbits/netshot/) for netshot is available.  To run, please consult\nthe [documentation](https://github.com/handcraftedbits/docker-netshot#usage).\n\n### Logging\n\nNetshot uses [Bunyan](https://github.com/trentm/node-bunyan) for logging.  It is recommended that you\n[install Bunyan](https://github.com/trentm/node-bunyan#installation) and pipe netshot through it for pretty logging\noutput:\n\n```bash\nnetshot | bunyan\n```\n\n# REST API\n\n* [Retrieve a listing of all screenshots: `GET /`](#get-)\n* [Create one or more screenshots: `POST /`](#post-)\n* [Retrieve a screenshot: `GET /:id`](#get-id)\n* [Delete a screenshot: `DELETE /:id`](#delete-id)\n* [Retrieve a list of emulated devices: `GET /devices`](#get-devices)\n* [Retrieves a list of emulated networks: `GET /networks`](#get-networks)\n\n## `GET /`\n\nRetrieve a listing of all screenshots.\n\n### Response\n\n#### Response Codes\n\n* `200` if successful.\n* `500` if an unexpected error occurs.\n\n#### Headers\n\n* `Content-Type`: `application/json`\n\n#### Body\n\nAn array of objects containing information about all captured screenshots.\n\n##### Schema\n\n```javascript\n[\n  {\n    // A unique identifier for the screenshot.\n    \"id\": \"string\",\n    // The URL used to retrieve or delete the screenshot.\n    \"href\": \"url\"\n  }\n]\n```\n\n### Example\n\n```bash\ncurl http://localhost:8000/\n```\n\n```http\nHTTP/1.1 200 OK\nContent-Type: application/json\nConnection: close\n\n[\n  {\n    \"id\": \"mTjgVBRPNPswZe4TQV5wpe.png\",\n    \"href\": \"http://localhost:8000/mTjgVBRPNPswZe4TQV5wpe.png\"\n  }\n]\n```\n\n## `POST /`\n\nCreate one or more screenshots.\n\n### Request\n\n#### Headers\n\n* `Content-Type`: `application/json`\n\n#### Body\n\nAn object containing information about the screenshot(s) to capture.\n\n##### Schema\n\n```javascript\n{\n  // Optional. The cookie(s) that should be included when loading the webpage.\n  \"cookie\": \"string | [ string, ... ]\",\n  // Optional. The CSS rule(s) that should be injected into the webpage after it is loaded.\n  \"css\": \"string | [ string, ... ]\",\n  // Optional. The amount of time, in milliseconds, that should elapse before a screenshot is taken.  When multiple\n  // delays are specified, multiple screenshots will be taken.\n  \"delay\": \"integer | [ integer, ... ]\"\n  // A JSON object describing an emulated device used to load the webpage.  See\n  // https://github.com/mixu/chromium-emulated-devices/blob/master/index.json for an example of the object format.\n  \"device\": \"object\",\n  // Optional. The screenshot format to use. Default: png\n  \"format\": \"string(jpg | pdf | png)\"\n  // Optional, but required if width is not specified. The maximum height of the screenshot either in pixels or as a\n  // device name.  By default, this will be the minimum height required to capture all the content on the webpage.\n  \"height\": \"integer | string\",\n  // Optional. Used to specify JPEG format settings. Only used if format=jpg.\n  \"jpg\": {\n    // Optional. JPEG quality level, expressed as an integer from 0 to 100. Default: 75.\n    \"quality\": \"integer\"\n  },\n  // Optional. The JavaScript code that should be injected into the webpage after it is loaded.\n  \"js\": \"string | [ string,... ]\",\n  // Optional, can be either a string or an object.  If a string, this value denotes an emulated network preset (you\n  // can find a complete listing of these presets by calling the /networks endpoint).  If an object, this value lets you\n  // create a custom emulated network.\n  \"network\": \"string\",\n  \"network\": {\n    // Optional.  The emulated network download speed, in Bps.\n    \"download\": \"integer\",\n    // Optional.  The emulated network latency, in ms.\n    \"latency\": \"integer\",\n    // Optional.  The emulated network upload speed, in Bps.\n    \"upload\" : \"integer\"\n  },\n  // Optional. Used to specify PDF format settings. Only used if format=pdf.\n  \"pdf\":\n    // Optional. Whether or not CSS backgrounds should be captured.\n    \"background\": \"boolean\",\n    // Optional. The page margins to use.\n    \"margin\": \"string(default | minimum | none)\",\n    // Optional. The page orientation to use.\n    \"orientation\": \"string(landscape | portrait)\",\n    // Optional. The paper size to use.\n    \"page-size\": \"string(A3 | A4 | legal | letter | tabloid)\"\n  },\n  // Optional. The CSS selector used to specify the DOM element that should be captured for the screenshot, instead of\n  // the entire page.\n  \"selector\": \"string\",\n  // Required. The URL of the webpage to load.\n  \"url\": \"string\",\n  // Optional. The user agent to present when loading the webpage.\n  \"user-agent\": \"string\",\n  // Required, but optional if height is specified. The maximum width of the screenshot either in pixels or as a device\n  // name.  By default, this will be the minimum width required to capture all the content on the webpage.\n  \"width\": \"integer | string\",\n  // Optional. The amount to zoom the webpage, expressed as a floating-point number from 1.0 to 3.0 (which corresponds\n  // to 100% to 300% zoom).\n  \"zoom-factor\": \"number\"\n}\n```\n\nConsult the [Electroshot documentation](https://github.com/mixu/electroshot#usage) for additional information on these\nparameters.\n\n### Response\n\n#### Response Codes\n\n* `201` if successful.\n* `500` if an unexpected error occurs.\n\n#### Headers\n\n* `Content-Type`: `application/json`\n\n#### Body\n\nAn array of objects containing information about the captured screenshot(s).\n\n##### Schema\n\n```javascript\n[\n  {\n    // A unique identifier for the screenshot.\n    \"id\": \"string\",\n    // The URL used to retrieve or delete the screenshot.\n    \"href\": \"url\"\n  }\n]\n```\n\n### Examples\n\nTake a single screenshot of `www.google.com` with the following settings:\n\n* Width of `1920` pixels\n* Minimum height required to capture all content\n* PNG (default) format\n\n```bash\ncurl -X POST -H \"Content-Type: application/json\" -d '{ \"url\": \"www.google.com\", \"width\": 1920 }' http://localhost:8000\n```\n\n```http\nHTTP/1.1 201 Created\nContent-Type: application/json\nContent-Length: 91\nConnection: close\n\n[\n  {\n    \"id\": \"fN9au2BsDfrLfc5Z8TVp9T.png\",\n    \"href\": \"http://dev01:8000/fN9au2BsDfrLfc5Z8TVp9T.png\"\n  }\n]\n```\n\nTake multiple screenshots of `www.google.com` with the following settings:\n\n* iPhone 6 dimensions\n* `500ms` delay before first screenshot and `1000ms` delay before second screenshot\n* JPEG format, maximum quality\n\n```bash\ncurl -X POST -H \"Content-Type: application/json\" -d '{ \"url\": \"www.google.com\", \"width\": \"Apple iPhone 6\", \"format\": \"jpg\", \"jpg\": { \"quality\": 100 }, \"delay\": [ 500, 1000 ] }' http://localhost:8000\n```\n\n```http\nHTTP/1.1 201 Created\nContent-Type: application/json\nContent-Length: 197\nConnection: close\n\n[\n  {\n    \"id\":\"sprYtfXc4p7yNzCc7nMmEb-1.jpg\",\n    \"href\":\"http://localhost:8000/sprYtfXc4p7yNzCc7nMmEb-1.jpg\"\n  },\n  {\n    \"id\":\"sprYtfXc4p7yNzCc7nMmEb-2.jpg\",\n    \"href\":\"http://localhost:8000/sprYtfXc4p7yNzCc7nMmEb-2.jpg\"\n  }\n]\n```\n\nTake a screenshot of `www.google.com` with the following settings:\n\n* Width of `1920` pixels\n* Minimum height required to capture all content\n* PDF format\n* No page margins, letter format\n\n```bash\ncurl -X POST -H \"Content-Type: application/json\" -d '{ \"url\": \"www.google.com\", \"width\": 1920, \"format\": \"pdf\", \"pdf\": { \"margin\": \"none\", \"page-size\": \"letter\" } }' http://localhost:8000\n```\n\n```http\nHTTP/1.1 201 Created\nContent-Type: application/json\nContent-Length: 95\nConnection: close\n\n[\n  {\n    \"id\":\"mUaGfeAs4QAke5oQDm4kjU.pdf\",\n    \"href\":\"http://localhost:8000/mUaGfeAs4QAke5oQDm4kjU.pdf\"\n  }\n]\n```\n\n## `GET /:id`\n\nRetrieve a screenshot.\n\n### Request\n\n#### Parameters\n\n* `id`: the ID of the screenshot to retrieve.\n\n### Response\n\n#### Response Codes\n\n* `200` if successful.\n* `404` if the screenshot cannot be found.\n\n#### Headers\n\n* `Content-Type`: `application/pdf`, `image/jpeg`, or `image/png` depending on format; `application/json` if an error occurs.\n\n#### Body\n\nRaw binary data containing the screenshot.\n\n### Example\n\n```bash\ncurl -o screenshot.pdf http://localhost:8000/mUaGfeAs4QAke5oQDm4kjU.pdf\n```\n\n## `DELETE /:id`\n\nDelete a screenshot.\n\n### Request\n\n#### Parameters\n\n* `id`: the ID of the screenshot to delete.\n\n### Response\n\n#### Response Codes\n\n* `204` if successful.\n* `404` if the screenshot cannot be found.\n\n#### Headers\n\n* `Content-Type`: `application/json`\n\n#### Example\n\n```bash\ncurl -X DELETE http://localhost:8000/mUaGfeAs4QAke5oQDm4kjU.pdf\n```\n\n## `GET /devices`\n\nRetrieve a list of emulated devices understood by netshot.  These devices can be referenced via the `height` and `width`\nproperties when creating a screenshot.\n\n### Response\n\n#### Response Codes\n\n* `200` if successful.\n\n#### Headers\n\n`Content-Type`: `application/json`\n\n#### Example\n\n```bash\ncurl http://localhost:8000/devices\n```\n\n```http\nHTTP/1.1 200 OK\nContent-Type: application/json\nContent-Length: 10365\nConnection: close\n\n{\n  \"Apple iPhone 4\": {\n    \"type\": \"phone\",\n    \"width\": 320,\n    \"height\": 480,\n    \"pixel-ratio\": 2,\n    \"user-agent\": \"Mozilla/5.0 (iPhone; U; CPU iPhone OS 4_2_1 like Mac OS X; en-us) AppleWebKit/533.17.9 (KHTML, like Gecko) Version/5.0.2 Mobile/8C148 Safari/6533.18.5\"\n  },\n  \"horizontal Apple iPhone 4\": {\n    \"type\": \"phone\",\n    \"width\": 480,\n    \"height\": 320,\n    \"pixel-ratio\": 2,\n    \"user-agent\": \"Mozilla/5.0 (iPhone; U; CPU iPhone OS 4_2_1 like Mac OS X; en-us) AppleWebKit/533.17.9 (KHTML, like Gecko) Version/5.0.2 Mobile/8C148 Safari/6533.18.5\"\n  },\n  \"Etc...\": {\n  }\n}\n```\n\n## `GET /networks`\n\nRetrieve a list of emulated networks understood by netshot.  These networks can by referenced via the `network` property\nwhen creating a screenshot.\n\n### Response\n\n#### Response Codes\n\n* `200` if successful.\n\n#### Headers\n\n`Content-Type`: `application/json`\n\n#### Example\n\n```bash\ncurl http://localhost:8000/networks\n```\n\n```http\nHTTP/1.1 200 OK\nContent-Type: application/json\nContent-Length: 514\nConnection: close\n\n{\n  \"Offline\": {\n    \"latency\": 0,\n    \"download\": 0,\n    \"upload\": 0\n  },\n  \"GPRS\": {\n    \"latency\": 500,\n    \"download\": 6400,\n    \"upload\": 6400\n  },\n  \"Etc...\": {\n  }\n}\n```","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhandcraftedbits%2Fnetshot","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhandcraftedbits%2Fnetshot","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhandcraftedbits%2Fnetshot/lists"}