Sindre Sorhus ef989fa555 readme - add note about setting 'user-agent' header		10 years ago
test	Improve error message on not 2xx code	10 years ago
.editorconfig	init	11 years ago
.gitattributes	init	11 years ago
.gitignore	Read response stream even if status is not 200	10 years ago
.jshintrc	init	11 years ago
.travis.yml	Update .travis.yml	10 years ago
index.js	Improve error message on not 2xx code	10 years ago
license	add gzip/deflate support	11 years ago
package.json	2.4.0	10 years ago
readme.md	readme - add note about setting 'user-agent' header	10 years ago

readme.md

got

Simplified HTTP/HTTPS requests

A nicer interface to the built-in http module.

It also supports following redirects, streams, and automagically handling gzip/deflate.

Created because request is bloated (several megabytes!) and slow.

Install

$ npm install --save got

Usage

var got = require('got');

// Callback mode
got('todomvc.com', function (err, data, res) {
	console.log(data);
	//=> <!doctype html> ...
});


// Stream mode
got('todomvc.com').pipe(fs.createWriteStream('index.html'));

// For POST, PUT and PATCH methods got returns a WritableStream
fs.createReadStream('index.html').pipe(got.post('todomvc.com'));

API

It's a GET request by default, but can be changed in options.

got(url, [options], [callback])

url

Required
Type: string

The URL to request.

options

Type: object

Any of the http.request options.

options.encoding

Type: string, null
Default: 'utf8'

Encoding to be used on setEncoding of the response data. If null, the body is returned as a Buffer.

options.body

Type: string, Buffer, ReadableStream

Body, that will be sent with POST request. If present in options and options.method is not set - options.method will be set to POST.

This option and stream mode are mutually exclusive.

options.timeout

Type: number

Milliseconds after which the request will be aborted and an error event with ETIMEDOUT code will be emitted.

options.agent

http.Agent instance.

Node HTTP/HTTPS Agent in 0.10 by default limits number of open sockets to 5 — which is too low. If options.agent is not defined got will use infinity-agent to backport defaultMaxSockets from 0.11.

Why pooling is evil.

To use default globalAgent just pass null to this option.

callback(err, data, response)

err

Error object with HTTP status code as code property.

data

The data you requested.

response

The response object.

got.get(url, [options], [callback])

got.post(url, [options], [callback])

got.put(url, [options], [callback])

got.patch(url, [options], [callback])

got.head(url, [options], [callback])

got.delete(url, [options], [callback])

Sets options.method to the method name and makes a request.

Proxy

You can use the tunnel module with the agent option to work with proxies:

var got = require('got');
var tunnel = require('tunnel');

got('todomvc.com', {
	agent: tunnel.httpOverHttp({
		proxy: {
			host: 'localhost'
		}
	})
}, function () {});

Tip

It's a good idea to set the 'user-agent' header so the provider can more easily see how their resource is used. By default it's the URL to this repo.

var got = require('got');

got('todomvc.com', {
	headers: {
		'user-agent': 'https://github.com/your-username/repo-name'
	}
}, function () {});