Google Maps API for Node.js

DEPRECATED: This package is no longer maintained. Please use Google's official Node.js client library @googlemaps/google-maps-services-js instead.

This library implements the following Google Maps APIs, and can be also used by Google Maps for Work users.

• Maps API Web Services
• Google Places API
• Google Maps Image API

This library is NOT COMPATIBLE with tags < 1.0.0

If you want to migrate from a version older than 1.0.0 check the WIKI for instructions.

Installation

npm install googlemaps

What does it cover

Maps API Web Services:

• Directions
• Distance matrix
• Elevation - TO BE IMPROVED
• Geocoding and reverse geocoding
• Time zone

Google Places API - NOT COMPLETED

• Place search
• Place details
• Place autocomplete
• Place text search

Google Maps Image API

• Static maps
• Street view - TO BE IMPROVED

Usage

var publicConfig = {
  key: '<YOUR-KEY>',
  stagger_time:       1000, // for elevationPath
  encode_polylines:   false,
  secure:             true, // use https
  proxy:              'http://127.0.0.1:9999' // optional, set a proxy for HTTP requests
};
var gmAPI = new GoogleMapsAPI(publicConfig);

// or in case you are using Google Maps for Work
var enterpriseConfig = {
  google_client_id:   '<YOUR-CLIENT-ID>', // to use Google Maps for Work
  google_private_key: '<YOUR-PRIVATE-KEY>', // to use Google Maps for Work
  google_channel:     '<YOUR-CHANNEL>' // to use Google Maps for Work application usage tracking
  stagger_time:       1000, // for elevationPath
  encode_polylines:   false,
  secure:             true, // use https
  proxy:              'http://127.0.0.1:9999' // optional, set a proxy for HTTP requests
};
var gmAPI = new GoogleMapsAPI(enterpriseConfig);

// geocode API
var geocodeParams = {
  "address":    "121, Curtain Road, EC2A 3AD, London UK",
  "components": "country:GB",
  "bounds":     "55,-1|54,1",
  "language":   "en",
  "region":     "uk"
};

gmAPI.geocode(geocodeParams, function(err, result){
  console.log(result);
});

// reverse geocode API
var reverseGeocodeParams = {
  "latlng":        "51.1245,-0.0523",
  "result_type":   "postal_code",
  "language":      "en",
  "location_type": "APPROXIMATE"
};

gmAPI.reverseGeocode(reverseGeocodeParams, function(err, result){
  console.log(result);
});

Check out the unit tests for more APIs examples.

Optional configuration

The following config keys control behavior that was added as bug fixes but could break existing callers. Each defaults to the old (pre-fix) behavior so existing code keeps working unless you opt in.

Key	Type	Default	Description
static_map_binary	boolean	false	When true, staticMap returns image data as a Buffer instead of a string. Use this if you save the image to a file (the old string output produced unusable files).
static_map_warnings	boolean	false	When true, Google's X-StaticMap-API-Warning response header is surfaced as a non-fatal error (err.isWarning = true) in the staticMap callback, alongside the image data. By default warnings are silently ignored.
places_default_radius	boolean	true	When true, placeSearch defaults radius to 50000 meters (the max) if omitted and rankby=prominence. Set to false to omit the radius entirely (Google ranks differently without it).
google_api_url	string	http://maps.googleapis.com	Override the base API URL forHTTP requests. Useful for mocking in tests.
google_secure_api_url	string	https://maps.googleapis.com	Override the base API URL for HTTPS requests.

Mocking responses

To mock the Google API endpoints for local development or CI, override the base URLs in your config:

var config = {
  key:                  '<YOUR-KEY>',
  google_api_url:       'http://localhost:3000/fixture',
  google_secure_api_url: 'https://localhost:3443/fixture'
};
var gmAPI = new GoogleMapsAPI(config);

Static Maps

var gmAPI = new GoogleMapsAPI();
var params = {
  center: '444 W Main St Lock Haven PA',
  zoom: 15,
  size: '500x400',
  maptype: 'roadmap',
  markers: [
    {
      location: '300 W Main St Lock Haven, PA',
      label   : 'A',
      color   : 'green',
      shadow  : true
    },
    {
      location: '444 W Main St Lock Haven, PA',
      icon: 'http://chart.apis.google.com/chart?chst=d_map_pin_icon&chld=cafe%7C996600'
    }
  ],
  style: [
    {
      feature: 'road',
      element: 'all',
      rules: {
        hue: '0x00ff00'
      }
    }
  ],
  path: [
    {
      color: '0x0000ff',
      weight: '5',
      points: [
        '41.139817,-77.454439',
        '41.138621,-77.451596'
      ]
    }
  ]
};
gmAPI.staticMap(params); // return static map URL
gmAPI.staticMap(params, function(err, binaryImage) {
  // fetch asynchronously the binary image
});

This example prints the URL for the Static Map image: "https://maps.googleapis.com/maps/api/staticmap?center=444%20W%20Main%20St%20Lock%20Haven%20PA&zoom=15&size=500x400&maptype=roadmap&markers=color%3Agreen%7Clabel%3AA%7Cshadow%3Atrue%7C300%20W%20Main%20St%20Lock%20Haven%2C%20PA&markers=icon%3Ahttp%3A%2F%2Fchart.apis.google.com%2Fchart%3Fchst%3Dd_map_pin_icon%26chld%3Dcafe%257C996600%7C444%20W%20Main%20St%20Lock%20Haven%2C%20PA&path=weight%3A5%7Ccolor%3A0x0000ff%7Cenc%3A%7BbbzFfyvwMnFwP&style=feature%3Aroad%7Celement%3Aall%7Chue%3A0x00ff00"

By giving gm.staticMap an optional callback, you can retreive the static map PNG data:

You will get a map like:

For custom markers using the icon parameter, a little-known scale parameter is also available that makes it possible to use high-resolution custom images on devices with retina displays. Set it to 2 and use it together with a @2x http-only image URL (Google's API does not support custom marker images served over https), such as:

{
  location: '999 Example Road, Earth',
  icon: 'http://example.com/path/to/custom-marker@2x.png',
  scale: 2
}

Credits to this answer on SO.

Street view

var gmAPI = new GoogleMapsAPI();
var params = {
  location: '51.507868,-0.087689',
  size: '1200x1600',
  heading: 108.4,
  pitch: 7,
  fov: 40
};
var result = gmAPI.streetView(params);

Further examples

Please refer to the code, tests and the Google Maps API docs for further usage information.

Tests

The unit tests run offline with no credentials:

npm test

The integration tests make real requests to the Google Maps API and require a valid, billing-enabled API key. Provide it via the GOOGLE_MAPS_API_KEY environment variable (no key is committed to this repository):

GOOGLE_MAPS_API_KEY=your-key-here npm run integration-test

GOOGLE_MAPS_SECURE may be set to false to use http (defaults to true / https). For local development you may instead create a git-ignored test/simpleConfig.json of the form {"key": "...", "secure": true}.

Contributions

Criticism/Suggestions/Patches/PullRequests are welcome.

Original contributors list

v1.0.0 maintener

Contributions and new issues are welcome!