Top Related Projects
Promise based HTTP client for the browser and node.js
🏊🏾 Simplified HTTP request client.
A light-weight module that brings the Fetch API to Node.js
Ajax for Node.js and browsers (JS HTTP client). Maintained for @forwardemail, @ladjs, @spamscanner, @breejs, @cabinjs, and @lassjs.
The all-batteries-included GitHub SDK for Browsers, Node.js, and Deno.
Quick Overview
Got is a human-friendly and powerful HTTP request library for Node.js. It's designed to be a simpler, more intuitive alternative to the popular request
library, with a focus on performance, reliability, and ease of use.
Pros
- Lightweight and fast compared to alternatives
- Promise-based API with support for async/await
- Built-in request retrying and timeout handling
- Extensive documentation and active community support
Cons
- Not compatible with browsers (Node.js only)
- Learning curve for users transitioning from other HTTP libraries
- Some advanced features may require additional configuration
Code Examples
Basic GET request:
import got from 'got';
const response = await got('https://api.example.com/data');
console.log(response.body);
POST request with JSON payload:
const { body } = await got.post('https://api.example.com/submit', {
json: {
name: 'John Doe',
age: 30
}
});
console.log(body);
Handling errors and retries:
try {
const response = await got('https://api.example.com/data', {
retry: {
limit: 3,
methods: ['GET']
}
});
console.log(response.body);
} catch (error) {
console.error('Request failed:', error.message);
}
Getting Started
- Install Got using npm:
npm install got
- Import and use Got in your Node.js project:
import got from 'got';
(async () => {
try {
const response = await got('https://api.example.com/data');
console.log(response.body);
} catch (error) {
console.error('An error occurred:', error.message);
}
})();
This example demonstrates a basic GET request using Got. The library supports various HTTP methods, request configurations, and response handling options. Refer to the official documentation for more advanced usage and features.
Competitor Comparisons
Promise based HTTP client for the browser and node.js
Pros of Axios
- Browser support: Axios works in both Node.js and browsers, making it versatile for full-stack development
- Automatic request and response transformations, including JSON parsing
- Built-in CSRF protection and request cancellation features
Cons of Axios
- Larger bundle size compared to Got, which may impact performance in some applications
- Less extensive feature set for advanced HTTP operations and streaming
- Not as actively maintained as Got, with slower release cycles
Code Comparison
Axios:
const axios = require('axios');
axios.get('https://api.example.com/data')
.then(response => console.log(response.data))
.catch(error => console.error(error));
Got:
const got = require('got');
(async () => {
try {
const response = await got('https://api.example.com/data');
console.log(response.body);
} catch (error) {
console.error(error);
}
})();
Both libraries offer similar basic functionality for making HTTP requests. Axios uses a promise-based approach by default, while Got provides both promise-based and async/await syntax out of the box. Got's syntax is slightly more concise, especially when using async/await.
🏊🏾 Simplified HTTP request client.
Pros of Request
- Mature and widely adopted library with extensive ecosystem
- Simpler API for basic use cases
- Better support for older Node.js versions
Cons of Request
- No longer actively maintained (deprecated)
- Larger bundle size
- Lacks some modern features like HTTP/2 support
Code Comparison
Request:
const request = require('request');
request('https://api.example.com', (error, response, body) => {
console.log('body:', body);
});
Got:
const got = require('got');
(async () => {
const response = await got('https://api.example.com');
console.log('body:', response.body);
})();
Got offers a more modern, Promise-based API with async/await support, while Request uses a callback-based approach. Got also provides a more streamlined syntax for common HTTP operations.
Both libraries support similar features like custom headers, query parameters, and request body, but Got generally offers a more concise and up-to-date implementation. Additionally, Got includes built-in retry functionality and better error handling, making it a more robust choice for modern Node.js applications.
A light-weight module that brings the Fetch API to Node.js
Pros of node-fetch
- Lightweight and simple API, closely mimicking the browser's Fetch API
- Easier to use for developers familiar with browser-based JavaScript
- Better suited for projects that prioritize simplicity and browser compatibility
Cons of node-fetch
- Less feature-rich compared to got, lacking advanced functionality out of the box
- Requires additional setup for features like automatic retries and pagination
- May need third-party libraries for more complex use cases
Code Comparison
node-fetch:
import fetch from 'node-fetch';
const response = await fetch('https://api.example.com/data');
const data = await response.json();
got:
import got from 'got';
const data = await got('https://api.example.com/data').json();
Summary
node-fetch provides a simpler, more browser-like API for making HTTP requests in Node.js environments. It's ideal for developers who prefer a familiar interface and don't need advanced features out of the box. However, for more complex use cases or projects requiring extensive functionality, got offers a more comprehensive solution with built-in features like retries, pagination, and caching.
The choice between node-fetch and got depends on the specific needs of your project, with node-fetch being better suited for simpler applications and got offering more power for complex scenarios.
Ajax for Node.js and browsers (JS HTTP client). Maintained for @forwardemail, @ladjs, @spamscanner, @breejs, @cabinjs, and @lassjs.
Pros of Superagent
- More mature and established project with a longer history
- Supports both Node.js and browser environments out of the box
- Offers a chainable API for more readable and expressive code
Cons of Superagent
- Larger bundle size compared to Got
- Less active development and slower release cycle
- Fewer built-in features for advanced use cases (e.g., rate limiting, retries)
Code Comparison
Superagent:
superagent
.get('https://api.example.com/data')
.query({ limit: 10 })
.set('Authorization', 'Bearer token')
.end((err, res) => {
if (err) console.error(err);
console.log(res.body);
});
Got:
got('https://api.example.com/data', {
searchParams: { limit: 10 },
headers: { Authorization: 'Bearer token' }
})
.json()
.then(response => console.log(response))
.catch(error => console.error(error));
Both libraries provide similar functionality for making HTTP requests, but Got offers a more modern Promise-based API and additional features. Superagent's chainable API can be more readable for some developers, while Got's approach is more concise and aligned with modern JavaScript practices.
The all-batteries-included GitHub SDK for Browsers, Node.js, and Deno.
Pros of Octokit.js
- Specifically designed for GitHub API interactions, offering comprehensive coverage of GitHub-related operations
- Provides TypeScript support out of the box, enhancing developer experience with better type checking and autocompletion
- Offers authentication helpers and plugins for extended functionality
Cons of Octokit.js
- Limited to GitHub API interactions, not suitable for general-purpose HTTP requests
- May have a steeper learning curve for developers unfamiliar with GitHub's API structure
- Larger package size compared to Got, which could impact bundle size in client-side applications
Code Comparison
Octokit.js example:
const octokit = new Octokit({ auth: 'token' });
const { data } = await octokit.rest.repos.get({
owner: 'octokit',
repo: 'octokit.js'
});
Got example:
const got = require('got');
const { body } = await got('https://api.github.com/repos/octokit/octokit.js', {
headers: { Authorization: 'token YOUR_TOKEN' }
});
const data = JSON.parse(body);
Both libraries offer efficient ways to interact with APIs, but Octokit.js provides a more tailored experience for GitHub-specific operations, while Got offers a more general-purpose HTTP client with a simpler API for various types of requests.
Convert designs to code with AI
Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.
Try Visual CopilotREADME
Sindre's open source work is supported by the community.
Special thanks to:
Human-friendly and powerful HTTP request library for Node.js
See how Got compares to other HTTP libraries
You probably want Ky instead, by the same people. It's smaller, works in the browser too, and is more stable since it's built upon Fetch
.
Support questions should be asked here.
Install
npm install got
Warning: This package is native ESM and no longer provides a CommonJS export. If your project uses CommonJS, you will have to convert to ESM. Please don't open issues for questions regarding CommonJS / ESM.
Got v11 is no longer maintained and we will not accept any backport requests.
Take a peek
A quick start guide is available.
JSON mode
Got has a dedicated option for handling JSON payload.
Furthermore, the promise exposes a .json<T>()
function that returns Promise<T>
.
import got from 'got';
const {data} = await got.post('https://httpbin.org/anything', {
json: {
hello: 'world'
}
}).json();
console.log(data);
//=> {"hello": "world"}
For advanced JSON usage, check out the parseJson
and stringifyJson
options.
For more useful tips like this, visit the Tips page.
Highlights
Documentation
By default, Got will retry on failure. To disable this option, set options.retry.limit
to 0.
Main API
Timeouts and retries
Advanced creation
Cache, Proxy and UNIX sockets
Integration
Migration guides
Got plugins
got4aws
- Got convenience wrapper to interact with AWS v4 signed APIsgh-got
- Got convenience wrapper to interact with the GitHub APIgl-got
- Got convenience wrapper to interact with the GitLab APIgotql
- Got convenience wrapper to interact with GraphQL using JSON-parsed queries instead of stringsgot-fetch
- Got with afetch
interfacegot-scraping
- Got wrapper specifically designed for web scraping purposesgot-ssrf
- Got wrapper to protect server-side requests against SSRF attacks
Comparison
got | node-fetch | ky | axios | superagent | |
---|---|---|---|---|---|
HTTP/2 support | :heavy_check_mark:¹ | :x: | :heavy_check_mark: | :x: | :heavy_check_mark:** |
Browser support | :x: | :heavy_check_mark:* | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: |
Promise API | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: |
Stream API | :heavy_check_mark: | Node.js only | :x: | :x: | :heavy_check_mark: |
Pagination API | :heavy_check_mark: | :x: | :x: | :x: | :x: |
Request cancelation | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: |
RFC compliant caching | :heavy_check_mark: | :x: | :x: | :x: | :x: |
Cookies (out-of-the-box) | :heavy_check_mark: | :x: | :x: | :x: | :x: |
Follows redirects | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: |
Retries on failure | :heavy_check_mark: | :x: | :heavy_check_mark: | :x: | :heavy_check_mark: |
Progress events | :heavy_check_mark: | :x: | :heavy_check_mark:*** | Browser only | :heavy_check_mark: |
Handles gzip/deflate | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: |
Advanced timeouts | :heavy_check_mark: | :x: | :x: | :x: | :x: |
Timings | :heavy_check_mark: | :x: | :x: | :x: | :x: |
Errors with metadata | :heavy_check_mark: | :x: | :heavy_check_mark: | :heavy_check_mark: | :x: |
JSON mode | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: |
Custom defaults | :heavy_check_mark: | :x: | :heavy_check_mark: | :heavy_check_mark: | :x: |
Composable | :heavy_check_mark: | :x: | :x: | :x: | :heavy_check_mark: |
Hooks | :heavy_check_mark: | :x: | :heavy_check_mark: | :heavy_check_mark: | :x: |
Issues open | |||||
Issues closed | |||||
Downloads | |||||
Coverage | TBD | ||||
Build | |||||
Bugs | |||||
Dependents | |||||
Install size | |||||
GitHub stars | |||||
TypeScript support | |||||
Last commit |
* It's almost API compatible with the browser fetch
API.
** Need to switch the protocol manually. Doesn't accept PUSH streams and doesn't reuse HTTP/2 sessions.
*** Currently, only DownloadProgress
event is supported, UploadProgress
event is not supported.
¹ Requires Node.js 15.10.0 or above.
:sparkle: Almost-stable feature, but the API may change. Don't hesitate to try it out!
:grey_question: Feature in early stage of development. Very experimental.
Click here to see the install size of the Got dependencies.
Maintainers
Sindre Sorhus | Szymon Marczak |
These amazing companies are using Got
Segment is a happy user of Got! Got powers the main backend API that our app talks to. It's used by our in-house RPC client that we use to communicate with all microservices.
â Vadim Demedes
Antora, a static site generator for creating documentation sites, uses Got to download the UI bundle. In Antora, the UI bundle (aka theme) is maintained as a separate project. That project exports the UI as a zip file we call the UI bundle. The main site generator downloads that UI from a URL using Got and streams it to vinyl-zip to extract the files. Those files go on to be used to create the HTML pages and supporting assets.
â Dan Allen
GetVoIP is happily using Got in production. One of the unique capabilities of Got is the ability to handle Unix sockets which enables us to build a full control interfaces for our docker stack.
â Daniel Kalen
We're using Got inside of Exoframe to handle all the communication between CLI and server. Exoframe is a self-hosted tool that allows simple one-command deployments using Docker.
â Tim Ermilov
Karaoke Mugen uses Got to fetch content updates from its online server.
â Axel Terizaki
Renovate uses Got, gh-got and gl-got to send millions of queries per day to GitHub, GitLab, npmjs, PyPi, Packagist, Docker Hub, Terraform, CircleCI, and more.
â Rhys Arkins
Resistbot uses Got to communicate from the API frontend where all correspondence ingresses to the officials lookup database in back.
â Chris Erickson
Natural Cycles is using Got to communicate with all kinds of 3rd-party REST APIs (over 9000!).
â Kirill Groshkov
Microlink is a cloud browser as an API service that uses Got widely as the main HTTP client, serving ~22M requests a month, every time a network call needs to be performed.
â Kiko Beats
Weâre using Got at Radity. Thanks for such an amazing work!
â Mirzayev Farid
Top Related Projects
Promise based HTTP client for the browser and node.js
🏊🏾 Simplified HTTP request client.
A light-weight module that brings the Fetch API to Node.js
Ajax for Node.js and browsers (JS HTTP client). Maintained for @forwardemail, @ladjs, @spamscanner, @breejs, @cabinjs, and @lassjs.
The all-batteries-included GitHub SDK for Browsers, Node.js, and Deno.
Convert designs to code with AI
Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.
Try Visual Copilot