TypeScript icon, indicating that this package has built-in type declarations

1.1.0 • Public • Published


A free, open-source light-weighted javascript library to get a detailed geolocation of IP address as well as to find where you are. Works on both browser side and non-browser side!


🐰 No API key is required

🐰 Full TypeScript support

🐰 Support remote IP address

🐰 Support usage with proxy settings

🐰 Free, open source, light-weighted

🐰 Works on both browser side and non-browser side


npm i findme-js



/** Works on ESM. If you are using CommonJS, refer to next section. */
import {getGeoInfo} from 'findme-js';

/** Get the geolocation of me */
console.log(await getGeoInfo());

 * Get the geolocation of me via system proxy settings.
 * This only works on non-browser side as in browser side the
 * proxy settings are always determined by your browser.
console.log(await getGeoInfo('', 'system'));

 * Get the geolocation of a certain remote address.
console.log(await getGeoInfo('');


Notice: This library is an ESM. You must use it in module scope, and depends on the type of your module, the ways to import may differ.


import {getGeoInfo} from 'findme-js';

In CommonJS

You must use dynamic-import to import an ESM.

import('findme-js').then(data => {
  const getGeoInfo = data.geoInfo();
  // ...

You may wrap it in an asynchronous function and use IIFE in order to use it in a more elegant way to avoid importing it multiple times.

const getGeoInfoPromise = (async () =>
  (await import('findme-js')).getGeoInfo)();
async function main() {
  const getGeoInfo = await getGeoInfoPromise;
  // ...


Function: getGeoInfo

getGeoInfo: (ip: string = '', proxySettings: ProxySettings = 'none') =>
Parameters Type Default Description
ip string '' The IP address of which you want to get the geolocation. You can also pass a domain name instead. Both valid IPv4 and IPv6 addresses are supported. Setting it to empty string to get your own geolocation.
proxySettings ProxySettings 'none' 'none': Don't use a proxy server.
'system': Use system proxy settings.
[Object AxiosProxyConfig]: You can also pass an AxiosProxyConfig object to customize your own proxy settings.
Notice: This parameter will be ignored in browser side! The proxy settings will always be determined by the browser in and you are not able to override it.

Interface: GeoInfo

The data structure is consistent with the returned data of, but with status and message field omitted.


The data source of Findme.js comes from the free open API of

Due to the usage limit of 45 requests per minute (refer to for more information), it may be not a good choice to use it in a high-payload environment.


Clone this repository.

Install the dependencies.

npm i

To build the library, run

npm run build

To run the test, run

npm run dev

You can also pass options to define which test to run. For more information use

npm run dev -- -h


This library is licensed under GNU Affero General Public License 3.0.

As this library uses the free open API of, you must also comply their user terms to use this library, that is, you can only use this library for a NON-COMMERCIAL purpose and in a NON-COMMERCIAL environment, otherwise the grant of usage will be regarded INVALID. Findme.js shall not be liable for any result caused by such illegal usages.

Package Sidebar


npm i findme-js

Weekly Downloads






Unpacked Size

42.3 kB

Total Files


Last publish


  • cherrai