gip/README.md

Get your public IPv4 address

# 🐷 GIP (Get IP)

[GIP](https://www.npmjs.com/package/gip) is a [Node.js](https://nodejs.org/en/) dependency-free tool for getting Public
[IPv4](https://en.wikipedia.org/wiki/IPv4) address using "IP echo" services. It will fetch data from multiple services at the same time to
give you results as fast as possible.

By default, GIP checks if an IP address is real by waiting for three same responses from different services. You can change this number by
adjusting the `ensure` option.

GIP offers over 20 services, and you can also add your own services using the `services` option. However, be aware that some services might
not always be available or may not work properly. That's why it's a good idea to keep the `ensure` count at a reasonable level.

Below you can find some examples of how to use these options.

## Requirements

[NodeJS](https://nodejs.org/en/download) version **20.0.0** or higher.

## [Module](https://nodejs.org/api/esm.html#modules-ecmascript-modules) installation

[NPM](https://docs.npmjs.com/cli/v10/commands/npm-install)

```bash
npm i gip
```

[BUN](https://bun.sh/docs/cli/add)

```bash
bun add gip
```

[DENO](https://docs.deno.com/runtime/reference/cli/add/)

```bash
deno add npm:gip
```

[PNPM](https://pnpm.io/pnpm-cli#commands)

```bash
pnpm add gip
```

## [Module](https://nodejs.org/api/esm.html#modules-ecmascript-modules) usage

```js
import gip from "gip";

try {
  const ip = await gip();
  console.log(ip);
} catch (error) {
  console.log(`Can't get your IP. Reason: ${error}`);
}
```

Usage with **options**

```js
import gip from "gip";

const options = {
  services: ["ipv4.icanhazip.com", "ifconfig.me/ip"],
  ensure: 10,
};

try {
  const ip = await gip(options);
  console.log(ip);
} catch (error) {
  console.log(`Can't get your IP. Reason: ${error}`);
}
```

## [CLI](https://en.wikipedia.org/wiki/Command-line_interface) installation

[NPM](https://docs.npmjs.com/downloading-and-installing-packages-globally)

```bash
npm i -g gip
```

[BUN](https://bun.sh/docs/cli/install#global-packages)

```bash
bun i -g gip
```

[DENO](https://docs.deno.com/runtime/reference/cli/install/#global-installation)

```bash
deno i -g npm:gip
```

[PNPM](https://pnpm.io/cli/add#--global--g)

```bash
pnpm add -g gip
```

## [CLI](https://en.wikipedia.org/wiki/Command-line_interface) usage

```bash
gip
# 133.74.20.69
```

Passing custom services

```bash
gip --services "https://ipv4.icanhazip.com/" "https://ifconfig.me/ip"
# 133.74.20.69
```

Setting ensure option

```bash
gip --ensure 10
# 133.74.20.69
```

## [CLI](https://en.wikipedia.org/wiki/Command-line_interface) usage without installation

[NPM]()

```bash
npx gip
```

[BUN](https://bun.sh/docs/cli/bunx)

```bash
bunx gip
```

[DENO](https://docs.deno.com/runtime/reference/cli/run/)

```bash
deno run --allow-net npm:gip
```

[PNPM](https://pnpm.io/pnpm-cli#commands)

```bash
pnpm dlx gip
```

## Additional info

- Passing your own services will not prioritize them. You will get answer from the fastest services anyway. List of services is located in
  file [services.mjs](https://github.com/Avaray/gip/blob/main/services.mjs)
- If you pass service without specified [protocol](https://en.wikipedia.org/wiki/Hypertext_Transfer_Protocol) -
  [GIP](https://www.npmjs.com/package/gip) will treat it as [HTTPS](https://en.wikipedia.org/wiki/HTTPS)