gomshal

Extracts Shared locations from Google Maps 🌍🔎👨‍👩‍👧‍👦 to JSON for Node.js. Since there is no official API for Shared locations by Google, this library requires to set full username and password for Google account directly as input parameter.

Install

🔽 npm: npm install gomshal --save

Npm ignore scripts flag

❗️ Enabling npm scripts is necessary to install playwright. Using npm scripts, browsers are installed which can then be controlled automatically.

If you have set npm config get ignore-scripts to true, you will not be able to use npm run commands even you specify --ignore-scripts=false. This is because npm-run-all is used when running commands and this tool not forward npm ignore-scripts flag. You can disable ignore scripts with npm config set ignore-scripts false. If you want to only install after repository clone, you can call ignore script only temporary for that install with npm install --ignore-scripts=false.

Usage

🔧 Typescript minimal usage sample (if credentials are already set)

import { Gomshal } from 'gomshal';

const gomshal: Gomshal = new Gomshal();
gomshal.initialize();
gomshal.onLocations(console.log);

🔧 Typescript full example of usage with custom configuration and callback on new shared locations data detected

import { Gomshal, GConfiguration, GState } from 'gomshal';

async startGomshal() {
  // create new instance
  const gomshal: Gomshal = new Gomshal();
  // you can change any configuration parameter if you need
  const customConfiguration: GConfiguration = {headless: false, showDevTools: true};
  // initialize with custom configuration
  let state: GState = await gomshal.initialize(customConfiguration);
  // if state is login and password required then do specific steps to get shared locations data
  if (state === GState.LoginAndPassword ) {
    // set login and password to configuration and initialize next step
    const credentialsConfiguration: GConfiguration = {
      ...customConfiguration,
      ...{login: 'google@gmail.com', password: 'secretpassword'}
    };
    state = await gomshal.initialize(credentialsConfiguration);
  }
  // if 2FA confirmation on phone is required
  if (state === GState.TwoFactorConfirmation ) {
    // ask the user for confirmation on the phone (simulated by timeout)
    await new Promise(resolve => setTimeout(resolve, 60000));
    // and try again initialize without any other configuration
    state = await gomshal.initialize();
  }
  // catch any other error if you need
  // if state is LocationData then get last location data
  const locationData = gomshal.locations;
  // or set callback when new shared locations data are detected and print it to console
  gomshal.onLocations((locationData) => {
    for (let personIndex = 0; personIndex < locationData.entities?.length; personIndex++) {
      const entity = locationData.entities[personIndex];
      if (entity.position?.address != null) {
        console.log(entity.fullName + ': ' + entity.position?.address);
      }
    }
  });
}
startGomshal();

🔧 Javascript with CommonJS modules

const { Gomshal } = require('gomshal');

async function gomshalStart() {
  gomshal = new Gomshal();
  state = await gomshal.initialize({login: 'google@gmail.com', password: 'secretpassword'});
  console.log(gomshal.locations);
  gomshal.close();
}

gomshalStart();

Demo

💻 There is an beautifull 🌈 Electron demo inside this monorepo. You can run it using this steps:

• clone this repository git clone https://github.com/atiris/gomshal.git,
• open it cd gomshal and run npm install (ignore-scripts npm config must be set to false)
• start npm run demo

Development

💼 Clone this repository git clone https://github.com/atiris/gomshal.git, cd gomshal and run npm install.

How does this library work

❓ Since 2020 Google require javascript to log in. So we need full browser support for using Google Maps (or get cookies in another way). For that reason I tried to use a puppeteer. However, this library has trouble enabling login because Google can effectively identify browser control and declare such a browser unsuitable for login. Now I use playwright instead. This project has a similar focus, and so far allows for automated login without detection from Google.

❗️ Dependency instalation: npm i playwright --save has tens of megabytes and requires a full browser to run.

Windows development

It may be necessary to run Set-ExecutionPolicy -ExecutionPolicy RemoteSigned in powershell console (as Administrator).

Notes

Publishing to npm

1. Build typescript library: npm run build
2. Test before publish
   • create package: npm pack
   • move created package to npmtest directory: mv gomshal-*.tgz npmtest\
   • create package json in this directory and set some defaults for test:
     • "type": "commonjs", for commonjs test and
     • "type": "module", for es6 module test
   • install npm package from file: npm i gomshal-1.0.0.tgz --save
   • go to npmtest dir cd npmtest and run test for desired type:
     • node index.cjs.js for commonjs test and
     • node index.esm.js for es6 module test
3. Login to npm: npm login
4. Initial library publishing npm publish
5. Fix
   • bugfix or patch: npm version patch
   • features: npm version minor
   • breaking changes: npm version major

Background

📝 I was inspired by the node-google-shared-locations repository in which I am a contributor. I could no longer simply modify this library without significantly affecting the core library architecture, so I created a new one from the very beginning. Compared to the previous library, this library contains significant expansions, but it is also larger and more resource-intensive.

Created in Slovakia 🇸🇰