TypeScript Definitions for official GoogleMaps API for Node.js (https://github.com/googlemaps/google-maps-services-js)

_Typings-for-@google-maps-package.md

Typings for the @google/maps package

Forked from https://gist.github.com/lukas-zech-software/a7e4a23a6833ec1abb1fc836138f7822 (thanks to @lukas-zech-software!) and modified to include typings for the Directions API as well.

Hopefully, this will once be available officially from Google, see googlemaps/google-maps-services-js#42.

Usage

1. Install @google/maps if you haven't do so already: npm install @google/maps --save.

2. Edit your tsconfig.json to include a new directory under which the manual typings will be put:

{
"compilerOptions": {
  "typeRoots": [
      "node_modules/@types",
      "manual_types"
  ]
...
}

3. Save the file index.d.ts from this gist as manual_types/@google/maps/index.d.ts.

4. Save an empty index.d.ts file as manual_types/@google/index.d.ts. (I had to do this, otherwise tsc would exit with "error TS2688: Cannot find type definition file for '@google'.")

5. You should now be able to write import * as googleMaps from '@google/maps'. Try reloading your editor if errors are shown.

index.d.ts

declare module "@google/maps" {
	export interface CreateClientOptions {
		/**
		 * API key (required, unless clientID and
		 * clientSecret provided).
		 */
		key: string;
		/**
		 * Maps API for Work client ID.
		 */
		clientId?: string;
		/**
		 * Maps API for Work client secret (a.k.a. private key).
		 */
		clientSecret?: string;
		/**
		 * Maps API for Work channel.
		 */
		channel?: string;
		/**
		 * Timeout in milliseconds. (Default: 60 * 1000 ms)
		 */
		timeout?: number;
		/**
		 * Promise constructor (optional).
		 * @constructor
		 */
		Promise?: PromiseConstructor;

		rate?: RateOptions;

		retryOptions?: RetryOptions;
	}

	export interface RateOptions {
		/**
		 * Controls rate-limiting of requests. Maximum number of requests per period.
		 * (Default: 10)
		 */
		limit: number;
		/**
		 * Period for rate limit, in milliseconds. (Default: 1000 ms)
		 */
		period: number;
	}

	export interface RetryOptions {
		/**
		 * If a transient server error
		 * occurs, how long to wait before retrying the request, in milliseconds.
		 * (Default: 500 ms)
		 */
		interval: number;
	}

	/**
	 * @see https://googlemaps.github.io/google-maps-services-js/docs/ResponseCallback.html
	 */
	export type MapApiResponseHandler<T> = (error: string|MapApiResponse<T>|any, response: MapApiResponse<T>) => void;

	/**
	 * HTTP Response of the API call
	 */
	export interface MapApiResponse<T> {
		/**
		 * HTTP Status Code
		 */
		status: number;

		/**
		 * HTTP Header object
		 */
		headers: { [index: string]: string };

		/**
		 * Payload of the API call
		 */
		json: T;
	}

	/**
	 * Payload of a Geocode response
	 */
	interface NodeAPIGeocodeResult {
		results: google.maps.GeocoderResult[];
		status: google.maps.GeocoderStatus;
	}

	export interface RequestHandle<T> {
		asPromise: () => Promise<MapApiResponse<T>>;
		cancel: () => void;
		finally: (callback: () => void) => this;
	}

	/**
	 * The [API exposed by the @google/maps package][1] slightly differs
	 * from the raw Directions API.
	 *
	 * [1]: https://googlemaps.github.io/google-maps-services-js/docs/GoogleMapsClient.html
	 * [2]: https://developers.google.com/maps/documentation/javascript/directions?hl=en#DirectionsRequests
	 */
	interface NodeAPIDirectionsRequest {
		/**
		 * TODO: According to [GoogleMapsClient#directions(query, callback)][1] from the Node.js API,
		 * string is not accepted. However, it is accepted from the raw Directions API and also works.
		 *
		 * [1]: https://googlemaps.github.io/google-maps-services-js/docs/GoogleMapsClient.html
		 */
		origin: google.maps.LatLng | string;
		/**
		 * TODO: According to [GoogleMapsClient#directions(query, callback)][1] from the Node.js API,
		 * string is not accepted. However, it is accepted from the raw Directions API and also works.
		 *
		 * [1]: https://googlemaps.github.io/google-maps-services-js/docs/GoogleMapsClient.html
		 */
		destination: google.maps.LatLng | string;
		mode?: string;
		waypoints?: google.maps.LatLng[];
		alternatives?: boolean;
		avoid?: string[];
		language?: string;
		units?: string;
		region?: string;
		departure_time?: Date | number;
		arrival_time?: Date | number;
		traffic_model?: string;
		transit_mode?: string[];
		transit_routing_preference?: string;
		optimize?: boolean;
	}

	interface NodeAPIDirectionsResult extends google.maps.DirectionsResult {
		status: google.maps.DirectionsStatus;
	}

	export class GoogleMapsClient {
		/**
		 * Call to the Geocode API
		 */
		public geocode(request: google.maps.GeocoderRequest, callback: MapApiResponseHandler<NodeAPIGeocodeResult>):
		  RequestHandle<NodeAPIGeocodeResult>;

		/**
		 * Call to the Directions API
		 * @param query
		 * @param callback
		 */
		public directions(query: NodeAPIDirectionsRequest, callback?: MapApiResponseHandler<google.maps.DirectionsResult>):
		  RequestHandle<NodeAPIDirectionsResult>;
	}

	export function createClient(options: CreateClientOptions): GoogleMapsClient;
}