# google-ips: Google IP Address Data Grouped by Country as an npm Package

> google-ips is a TypeScript npm package that provides a structured list of Google IP addresses organized by country, along with query helper functions for Node.js. The data comes from historical public collection results and is regenerated from a README table into a JSON file.

**justjavac/google-ips** — Google 全球 IP 地址库，按国家/地区整理并提供 npm 查询 API Google IP address list grouped by country with JSON data and query helpers.

- Repository: https://github.com/justjavac/google-ips
- Stars: 3,481 · Forks: 1,063
- Language: TypeScript
- License: not declared
- Published: 2026-09-23 · Updated: 2026-09-23 · Language: en
- Canonical page: https://hysenlabs.com/projects/justjavac-google-ips

## What google-ips Solves and Who Uses It

Developers who build geolocation tools, network firewalls, CDN configuration scripts, or traffic analysis systems sometimes need to identify whether a given IP address belongs to Google's infrastructure and, if so, which country that address is associated with. google-ips packages that dataset as a structured, queryable npm module.

The project provides two things: a generated JSON file (data/google-ips.json) containing Google IP addresses organized by country, and a TypeScript query library with helper functions that wrap the JSON data. The target audience is Node.js developers who want to do IP lookups in code rather than loading and parsing the raw JSON manually.

## Installing and Using the npm Package

The package is installed with:

```sh
npm install google-ips
```

The README shows five query operations available after installation:

```js
const googleIps = require("google-ips");

console.log(googleIps.ips.length);
console.log(googleIps.countries);
console.log(googleIps.getByCountry("Hong Kong"));
console.log(googleIps.has("93.123.23.1"));
console.log(googleIps.findCountry("118.174.25.251"));
```

These five operations cover the main lookup patterns: counting all IPs, listing all countries in the dataset, retrieving IPs for a specific country, checking whether a given IP is in the dataset, and finding the country associated with a given IP. The package requires Node.js 16 or greater, as specified in the package.json engines field.

Developers who only need the raw data without the query helpers can import the JSON directly:

```js
const data = require("google-ips/data");
```

## How the Data Is Structured and Generated

The README describes the data as coming from historical publicly collected results. The repository's build process generates data/google-ips.json from an HTML table in the README itself. The Makefile equivalent is the generate-data script in package.json:

```sh
npm run build
```

Running npm run build executes the full pipeline: it cleans the dist directory, runs generate-data to parse the README table and write the JSON, then compiles the TypeScript source with tsc.

The README includes the IP data inline as an HTML table organized by country. For example, the Bulgaria section begins with 93.123.23.1 through 93.123.23.59. The README is both human-readable documentation and the source of truth for the dataset. When a new IP address needs to be added or corrected, it is changed in the README table and the JSON is regenerated.

The package exports the compiled JavaScript from dist/src/index.js as its main entry point and exposes separate TypeScript declaration files. The data export at ./data maps to the compiled JSON copy in dist/data/google-ips.json.

## Limitation: Historical Data with No Automatic Synchronization

The README explicitly describes the dataset as coming from historical publicly collected results. There is no documented mechanism for automatically pulling fresh IP ranges from Google's infrastructure or from any authoritative source. Google does not publish a single official JSON feed of all its globally deployed IP addresses by country.

This means the dataset can become stale. An IP address that Google has assigned to a new data center after the last data collection will not appear in the package, and findCountry will return no match for it. Conversely, an IP that Google has relinquished may still appear in the dataset.

For applications where false negatives or false positives in Google IP detection carry significant consequences, teams should verify the dataset's coverage against their specific use case before relying on it.

## TypeScript Source and Build Configuration

The repository is written in TypeScript and uses two tsconfig files: tsconfig.json for the library source in src/ and tsconfig.scripts.json for the build and code generation scripts in scripts/. The devDependencies in package.json list only @types/node and typescript, keeping the build dependencies minimal.

The package.json exports field defines three entry points: the main library at ., the raw data at ./data, and the package metadata at ./package.json. Each entry point exposes both TypeScript type declarations and a CommonJS module. The typecheck script runs tsc --noEmit to validate types without producing output, and the test script runs the full build followed by the test runner in dist-scripts.

The top-level repository directories include src/ for the library code, scripts/ for the generation and test scripts, data/ for the JSON output, and test/ for the test suite.

## Comparison with ip-range-check and Similar Libraries

Libraries such as ip-range-check or cidr-regex handle the problem of testing whether an IP falls within a given CIDR block, but they do not include any IP data. The developer must supply the list of ranges to check against.

google-ips takes the opposite approach: it bundles the data and provides the lookup API together. This makes it immediately usable without sourcing or maintaining a separate IP list, at the cost of coupling the library version to the data vintage. A project that installs google-ips at a given point in time will use that snapshot's data until the package is updated. ip-range-check with a regularly refreshed list of CIDR ranges from an external source gives more control over data freshness but requires the developer to build and maintain that refresh pipeline.

The google-ips package structure separates the query helpers from the raw data through its exports field, which means a project that only needs the JSON can import it via the ./data entry point without pulling in the TypeScript-compiled helper functions. This is a minor but practical benefit for scripts that prefer direct JSON parsing over a library API.

## Conclusion

google-ips is a practical choice for Node.js projects that need programmatic access to a country-grouped list of Google IP addresses without building and maintaining that dataset themselves. The right question to verify before relying on it in production is data freshness: the README states the dataset comes from historical publicly collected results, and since it is not synchronized from an authoritative source, any newly added or changed Google IP range may be absent. The last push was on 2026-07-06. The package is available under the MIT license.

## FAQ

### What is google-ips?

google-ips is an npm package that provides Google IP addresses organized by country as a JSON dataset, along with TypeScript query helpers for Node.js. It lets developers check whether an IP belongs to Google and find which country that IP is associated with.

### How current is the IP address data in google-ips?

The README describes the data as coming from historical publicly collected results. There is no automatic synchronization with a live source, so the dataset reflects the state at the time of the last data collection and may not include recently added or changed Google IP ranges.

### Can google-ips be used in a TypeScript project?

The package is written in TypeScript and ships type declaration files for both the main library and the data export. The package.json exports field exposes TypeScript types alongside the compiled JavaScript for both entry points.

## Sources

- [Issues](https://github.com/justjavac/google-ips/issues)
- [justjavac/google-ips on GitHub](https://github.com/justjavac/google-ips)
- [README](https://github.com/justjavac/google-ips/blob/main/README.md)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/justjavac-google-ips