Gatsby Source Google Maps Static Plugin

GSGS (gatsby-source-googlemaps-static)

This source plugin for Gatsby will make location information from Google Maps available in GraphQL queries and provide a link to open that map on Google Maps. GSGS (gatsby-source-googlemaps-static) plugin will also cache the image response and only make a call to the API when the cache is invalid or empty. The cache is invalidated when you change any of the values below (Omitting the key and secret).

GSGS will also obscure your API key by only holding onto the key, or secret, when an API call is necessary. After the key, or secret, has been deemed unnecessary, it will be deleted from memory.

Install

# Install the plugin
npm install @ccalamos/gatsby-source-googlemaps-static

# or using Yarn
yarn add @ccalamos/gatsby-source-googlemaps-static

How to use

In gatsby-config.js:

Minimum Setup

module.exports = {
    plugins: [
        {
            resolve: `@ccalamos/gatsby-source-googlemaps-static`,
            options: {
                key: `YOUR_GOOGLE_MAPS_STATIC_API_KEY`,
                center: `LATITUDE,LONGITUDE || CITY,REGION`,
            },
        },
    ],
};

NOTE: To get a Google Maps Static API key, register for a Google Maps dev account.

Options

The configuration options for this plugin are currently an expansive set of the static API parameters. Please review those docs for more details and feel free to contribute to this repo to expand the accepted parameters.

module.exports = {
    plugins: [
        {
            resolve: `@ccalamos/gatsby-source-googlemaps-static`,
            options: {
                key: `YOUR_GOOGLE_MAPS_STATIC_API_KEY`,
                center: `LATITUDE,LONGITUDE || CITY,REGION`,
                zoom: `ZOOM_LEVEL`,
                size: `SIZE || WIDTHxHEIGHT`,
                scale: `SCALE_VALUE`,
                format: `IMAGE_EXTENSION`,
                mapType: `MAP_FORMAT`,
                mapID: `CLOUD_BASED_STYLE_MAP_ID`,
                styles:
                    [
                        {
                            feature: `FEATURE`,
                            element: `ELEMENT`,
                            rules: {
                                hue: `HUE`,
                                lightness: `LIGHTNESS`,
                                saturation: `SATURATION`,
                                gamma: `GAMMA`,
                                invert_lightness: true || false,
                                visibility: `VISIBILITY`,
                                color: `COLOR`,
                                weight: `WEIGHT`,
                            },
                        },
                    ],
                markers:
                    [
                        {
                            location: `LATITUDE,LONGITUDE || CITY,REGION`,
                            color: `COLOR`,
                            size: `SIZE`,
                            label: `A_SINGLE_ALPHANUMERIC_CHARACTER`,
                            icon: `URI`,
                            anchor: `ANCHOR_POSITION`,
                        },
                    ],
                paths:
                    [
                        {
                            weight: `WEIGHT`,
                            color: `COLOR`,
                            fillColor: `FILL_COLOR`,
                            geoDesic: true || false,
                            points: [`LATITUDE,LONGITUDE || CITY,REGION`],
                        },
                    ],
                visible:
                    [`LATITUDE,LONGITUDE || CITY,REGION`],
                clientID: `GOOGLE_MAPS_STATIC_CLIENT_ID`,
                secret: `GOOGLE_MAPS_SECRET_FOR_SIGNED_URLS`,
                query: `GOOGLE_MAPS_URL_QUERY`,
                nickname: `NICKNAME`,
                maps: [
                    {
                        `ALL_OPTIONS`,
                    }
                ],
            },
        },
    ],
};

| Option | Default | Description | Notes | | ---------- | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | key | | [required**] Your application's API key. This key identifies your application for purposes of quota management. | This is not required if you provide both clientID and secret | | center | | [required*] The latitude and longitude or address of the center of the map. | This is not required if you are using Implicit Mapping. See Google Maps Static Docs for more information. | | zoom | 14 | The zoom level of the map. | | size | 640x640 | The width and height of the image returned from Google. | It is optional to include the x character if the height and width are equal. | | scale | | The scale value for the map returned by Google. | | format | png | The file format and extension for the image. | | mapType | | The type of map that Google should use to render the image. | | mapID | | The ID from Google Cloud Based Maps. | | clientID | | [required**] The client ID from Google Cloud Platform Console. | This field is not required when using key field. | | secret | | [required*] The modified base64 secret from Google Cloud Platform Console used for signing URLs. | This field is only required when attempting to create a signature. | | query | | A custom query to replace your center for the generated map URL. | | styles | | Provides custom styles to the returned image. | Either a preformatted URI string or an Array of Objects. Please see Google Maps Static Styled Maps for more information about these fields. | | markers | | Places markers on the return map image. | Either a preformatted URI string or an Array of Objects. Please see Google Maps Static Markers for more information about these fields. | | paths | | Places a path or a polygonal area over top of the map. | Either a preformatted URI string or an Array of Objects. Please see Google Maps Static API Paths for more information about these fields. | | visible | | Ensures that the provided points are visible on the map. | Either a preformatted URI string or an Array of Strings. This has precedence over zoom level. Please see Google Maps Static Viewports for more information about these fields. | | nickname | | Used to add a nickname to the map, for ease of use with GraphQL | This field will default to using the hash ID if not specified. | | maps | | Used to add multiple maps to gatsby. | This field takes all the same options as the options field, however it will override the options field for that map. |

** If provided with both key and clientID, **GSGS** will prefer to use clientID.

If map is generated using Implicit Mapping, then the generated URL will be using Google Directions Waypoints. The first paths points will be the waypoints, if that is not provided then it will use the markers locations, if that is not provided then it will use the visible locations.

Example Configuration

A Very Simple Configuration Example

module.exports = {
    plugins: [
        {
            resolve: "@ccalamos/gatsby-source-googlemaps-static",
            options: {
                key: process.env.GOOGLE_MAPS_STATIC_API_KEY,
                center: "41.8781,-87.6298",
            },
        },
    ],
};

Another Very Simple Configuration Example

module.exports = {
    plugins: [
        {
            resolve: "@ccalamos/gatsby-source-googlemaps-static",
            options: {
                key: process.env.GOOGLE_MAPS_STATIC_API_KEY,
                center: "Chicago, IL",
            },
        },
    ],
};

An Implicit Mapping Configuration Example

module.exports = {
    plugins: [
        {
            resolve: `@ccalamos/gatsby-source-googlemaps-static`,
            options: {
                key: process.env.GOOGLE_MAPS_STATIC_API_KEY,
                paths: [
                    {
                        color: `0x00000000`,
                        weight: `5`,
                        fillColor: `0xFFFF0033`,
                        points: [
                            `8th Avenue & 34th St, New York, NY`,
                            `8th Avenue & 42nd St,New York,NY`,
                            `Park Ave & 42nd St,New York,NY,NY`,
                            `Park Ave & 34th St,New York,NY,NY`,
                        ],
                    },
                ],
            },
        },
    ],
};

Signature Configuration Example (Using API KEY)

module.exports = {
    plugins: [
        {
            resolve: `@ccalamos/gatsby-source-googlemaps-static`,
            options: {
                key: process.env.GOOGLE_MAPS_STATIC_API_KEY,
                secret: process.env.GOOGLE_MAPS_STATIC_SECRET,
                center: `New York, NY`,
            },
        },
    ],
};

Signature Configuration Example (Using Client ID)

module.exports = {
    plugins: [
        {
            resolve: `@ccalamos/gatsby-source-googlemaps-static`,
            options: {
                clientID: process.env.GOOGLE_MAPS_STATIC_CLIENT_ID,
                secret: process.env.GOOGLE_MAPS_STATIC_SECRET,
                center: `New York, NY`,
            },
        },
    ],
};

Query Configuration Example

module.exports = {
    plugins: [
        {
            resolve: `@ccalamos/gatsby-source-googlemaps-static`,
            options: {
                key: process.env.GOOGLE_MAPS_STATIC_API_KEY,
                center: `Chicago, IL`,
                query: `Willis Tower`,
            },
        },
    ],
};

Multiple Maps Example

module.exports = {
    plugins: [
        {
            resolve: `@ccalamos/gatsby-source-googlemaps-static`,
            options: {
                key: process.env.GOOGLE_MAPS_STATIC_API_KEY,
                styles: [
                    {
                        feature: `poi`,
                        element: `labels`,
                        rules: {
                            visibility: `off`,
                        },
                    },
                ],
                maps: [
                    {
                        center: `Chicago, IL`,
                        query: `Willis Tower`,
                    },
                    {
                        center: `Colorado Springs, CO`,
                        query: `Garden of the Gods`,
                    },
                    {
                        center: `Miami, FL`,
                        nickname: `Beach`,
                    },
                ],
            },
        },
    ],
};

Cloud Based Map Style ID

{
    resolve: `@ccalamos/gatsby-source-googlemaps-static`,
    options: {
        key: process.env.GOOGLE_MAPS_STATIC_API_KEY,
        center: `Chicago, IL`,
        mapID: `8f348d1b5a61d4bb`
    },
},

GraphQl Queries

Once the plugin is configured, one new query is available in GraphQL: staticMap.

Here’s an example query to load the image of a Static Map:

query StaticMapQuery {
    staticMap {
        childFile {
            childImageSharp {
              gatsbyImageData(layout: FIXED # or FLUID)
            }
        }
    }
}

Here’s an example query to get the generated Google Maps URL of the Static Map:

query StaticMapQuery {
    staticMap {
        mapUrl
    }
}

Here's an example of querying the multiple generated files to get one specific by the nickname:

query StaticMapQuery {
    allStaticMap(filter: { nickname: { eq: "Beach" } }) {
        edges {
            node {
                childFile {
                    childImageSharp {
                      gatsbyImageData(layout: FIXED # or FLUID)
                    }
                }
            }
        }
    }
}

If you are using format: 'gif' Image Sharp will not be able to process your image, however you can still access your cached/downloaded image like so:

query StaticMapGifQuery {
    staticMap {
        childFile {
            publicURL
        }
    }
}

See the Image Sharp Plugin or the GraphiQL UI for info on all returned fields.