@gmaps-kit/core

Framework-agnostic core utilities for Google Maps JavaScript SDK - geocoding, directions, places, markers, street view, and more.

🚀 Live Demo

Try it out: https://demo-app-rouge-five.vercel.app/

See all features in action with interactive examples!

Features

🗺️ Map Management - Create and manage Google Maps instances
📍 Geocoding - Convert addresses to coordinates and vice versa
🧭 Directions - Get driving, walking, and transit directions
🏢 Places - Search and get details about places
📌 Markers - Add, remove, and manage map markers
🛣️ Street View - Integrate Street View panoramas
🔍 Autocomplete - Add place autocomplete functionality
📦 Framework Agnostic - Works with any JavaScript framework
🎯 TypeScript - Full TypeScript support with type definitions
⚡ Lightweight - Optimized bundle size (~21KB)

Installation

npm install @gmaps-kit/core

Quick Start

1. Load Google Maps API

import { loadGoogleMaps } from '@gmaps-kit/core';

// Load Google Maps API
await loadGoogleMaps({
  apiKey: 'YOUR_API_KEY',
  libraries: ['places', 'geometry'],
});

2. Create a Map

import { createMap } from '@gmaps-kit/core';

const mapInstance = createMap('map-container', {
  center: { lat: 40.7128, lng: -74.006 },
  zoom: 10,
});

3. Add Markers

import { addMarker, createInfoWindow } from '@gmaps-kit/core';

// Add a marker
const marker = addMarker(mapInstance.map, {
  position: { lat: 40.7128, lng: -74.006 },
  title: 'New York City',
});

// Create an info window
const infoWindow = createInfoWindow({
  content: '<h3>New York City</h3><p>The Big Apple!</p>',
});

Core Features

Geocoding

import { geocode, reverseGeocode } from '@gmaps-kit/core';

// Convert address to coordinates
geocode('New York City', (results, status) => {
  if (status === 'OK') {
    console.log(results[0].geometry.location);
  }
});

// Convert coordinates to address
reverseGeocode({ lat: 40.7128, lng: -74.006 }, (results, status) => {
  if (status === 'OK') {
    console.log(results[0].formatted_address);
  }
});

Directions

import { getDirections, renderDirections } from '@gmaps-kit/core';

getDirections(
  {
    origin: 'New York, NY',
    destination: 'Boston, MA',
    travelMode: 'DRIVING',
  },
  (result, status) => {
    if (status === 'OK') {
      renderDirections(mapInstance.map, result);
    }
  }
);

Places (Legacy API)

import { PlacesClient } from '@gmaps-kit/core';

const placesClient = new PlacesClient({
  apiKey: 'YOUR_API_KEY',
});

// Search for places
const results = await placesClient.textSearch({
  query: 'restaurants in New York',
  location: { lat: 40.7128, lng: -74.006 },
  radius: 1000,
});

Places API (New) - Enhanced Features

import { PlacesNewClient } from '@gmaps-kit/core';

const placesNewClient = new PlacesNewClient({
  apiKey: 'YOUR_API_KEY',
});

// Text search with enhanced data
const textResults = await placesNewClient.textSearch({
  textQuery: 'restaurants in New York',
  locationBias: {
    circle: {
      center: { latitude: 40.7128, longitude: -74.006 },
      radius: 1000,
    },
  },
  maxResultCount: 10,
  minRating: 4.0,
});

// Nearby search with better CORS support
const nearbyResults = await placesNewClient.nearbySearch({
  includedTypes: ['restaurant', 'cafe'],
  locationRestriction: {
    circle: {
      center: { latitude: 40.7128, longitude: -74.006 },
      radius: 1000,
    },
  },
  maxResultCount: 10,
  minRating: 4.0,
});

// Get detailed place information
const placeDetails = await placesNewClient.placeDetails({
  placeId: 'ChIJN1t_tDeuEmsRUsoyG83frY4',
});

// Place autocomplete
const autocompleteResults = await placesNewClient.autocomplete({
  input: 'restaurants in',
  locationBias: {
    circle: {
      center: { latitude: 40.7128, longitude: -74.006 },
      radius: 1000,
    },
  },
});

// Get place photos
const photo = await placesNewClient.getPhoto({
  name: 'photos/123',
  maxWidthPx: 400,
  maxHeightPx: 300,
});

// Build photo URL
const photoUrl = placesNewClient.buildPhotoUrl('photos/123', {
  maxWidthPx: 400,
  maxHeightPx: 300,
});

Autocomplete

import { createAutocomplete, bindAutocompleteToMap } from '@gmaps-kit/core';

const autocomplete = createAutocomplete(
  document.getElementById('search-input'),
  {
    types: ['establishment'],
    componentRestrictions: { country: 'us' },
  }
);

bindAutocompleteToMap(autocomplete, mapInstance.map);

API Reference

Map Functions

createMap(container, options, eventHandlers?) - Create a new map instance
getMapCenter(map) - Get map center coordinates
setMapCenter(map, center) - Set map center
getMapZoom(map) - Get current zoom level
setMapZoom(map, zoom) - Set zoom level
panTo(map, location) - Pan to a location
fitMapToMarkers(map, markers) - Fit map to show all markers

Marker Functions

addMarker(map, options) - Add a marker to the map
removeMarker(marker) - Remove a marker
updateMarkerPosition(marker, position) - Update marker position
updateMarkerContent(marker, content) - Update marker content
setMarkerDraggable(marker, draggable) - Set marker draggable state

Geocoding Functions

geocode(address, callback) - Geocode an address
reverseGeocode(location, callback) - Reverse geocode coordinates
geocodeAsync(address) - Async geocoding
reverseGeocodeAsync(location) - Async reverse geocoding

Directions Functions

getDirections(request, callback) - Get directions
getDirectionsAsync(request) - Async directions
renderDirections(map, result) - Render directions on map
clearDirections(map) - Clear directions from map

TypeScript Support

This package includes full TypeScript definitions:

import type {
  MapOptions,
  MarkerOptions,
  GeocodingResult,
} from '@gmaps-kit/core';

const mapOptions: MapOptions = {
  center: { lat: 40.7128, lng: -74.006 },
  zoom: 10,
};

Browser Support

Chrome 60+
Firefox 55+
Safari 12+
Edge 79+

License

Contributing

Contributions are welcome! Please read our Contributing Guide for details.