Google Geocode Connector

Integration with Google's Geocode API

Introduction

Geocoding is the process of converting addresses , which users can use to place markers on a map, or position the map. Similarly, Reverse Geocoding is the process of converting geographic coordinates into a human-readable address.The goal of this connector is to integrate Google's Geocode API with Tulip using HTTP Connectors & provide our customers with an out of box Geocode connector that can be imported into their instance.

Purpose

1. We are going to highlight different HTTP connector functions that can be built by doing HTTP calls to Google's Geocode API endpoints to pull detailed information about an address, obtaining its co-ordinates that could be leveraged for various use cases. Using Reverse geocoding by passing in the co-ordinates & obtaining all the information on the address along with showcasing how to apply filters on these API calls.
2. Additionally, we are going to use Google's Distance Matrix API to showcase how one can pull information about the distance & the duration for travel between 2 addresses or co-ordinates obtained via Geocoding API as explained above.

API Doc

1. Google Geocode API Documentation
2. Google Distance Matrix API Documentation

Pre-Requisites

1. Create an account on Google's cloud Console & configure the API key for Google Geocode. More information can be found in Google's API docs.
2. The API key generated will be used as a query parameter in all the connector functions for Geocode & Distance Matrix. The users need to make sure they have their API Keys either passed via Tulip's input extractor or have it typed in all connector functions.

Tulip Connection Details

The following information would need to be configured on Tulip's connectors.

1. Running On: Cloud Connector Host
2. Host : maps.googleapis.com
3. Port:443
4. TLS:Yes
5. No Authentication needed: API key for each call will suffice.

Connector Functions

Getting Address Information

Purpose

1. Users can pass a search query as an input address & Tulip will fetch all the important information about the specific address & its equivalent Latitude & Longitude co-ordinates which can be further used as markers on maps or for other use cases one might have.
2. Information being pulled from Geocode can then be further used either within Tulip apps, Tulip tables or Tulip variables which would be piped into other connector functions that are part of Geocode Connector.

Endpoint

1. HTTP GET call to the endpoint - https://maps.googleapis.com:443/maps/api/geocode/json

Required Input

The following are the query parameters that are to be passed

1. API Key
2. Address - Address for the search query

Required Output Extractor

1. Full Address: Formatted full address returned by Google.
2. Latitude: Co-ordinates used for markers on map or used by passing in distance matrix API.
3. Longitude : Co-ordinates used for markers on map or used by passing in distance matrix API.
4. Location Type : Indicator for the kind of location searched for

Getting address information with Region

Purpose

1. This function is similar to the one described above with the option of passing an additional query parameter in the connector function. A lot of times an address would happen to be in multiple countries & in-order for getting the desired result, users can pass the country code in the region parameter of the connector function to make sure the results returned are from the country of interest.
2. Region being one of the query parameters users can leverage to filter the results however google offers many other query parameters that could be used in making these calls to Geocode API. More information on that could be found on the API docs.

Endpoint & Headers

1. HTTP GET call to the endpoint https://maps.googleapis.com:443/maps/api/geocode/json

Required Input

The following are the query parameters that are to be passed

1. API Key
2. Address - Address for the search query
3. Region - Country of interest

Required Output Extractors

1. Full Address: Formatted full address returned by Google.
2. Latitude: Co-ordinates used for markers on map or used by passing in distance matrix API.
3. Longitude : Co-ordinates used for markers on map or used by passing in distance matrix API.
4. Location Type : Indicator for the kind of location searched for

Reverse Geocoding

Purpose

1. Reverse Geocoding is the process of converting geographic coordinates into a human-readable address.
2. This connector function would take the co-ordinates as Input & return human readable address & all the other details like various address components that is returned by the API.

Endpoint & Headers

1. HTTP GET call to the endpoint https://maps.googleapis.com:443/maps/api/geocode/json

Required Input

The following are the query parameters that are to be passed

1. API Key
2. LatitudeLongitude: Users need to pass in the co-ordinates separated by comma.

Required Output Extractors

1. Full Address: Formatted full address returned by Google.
2. Location Type : Indicator for the kind of location searched for

Reverse Geocoding with Filters

Purpose

1. This connector function is used exactly like the one mentioned above however Geocode API returns multiple rows of results for the co-ordinates passed for a location. This function showcases how to leverage various query parameters offered by the API to filter the results to the one which is of interest

EndPoint & Headers

1. HTTP GET call to the endpoint https://maps.googleapis.com:443/maps/api/geocode/json

Required Input

The following are the query parameters that are to be passed

1. API Key
2. LatitudeLongitude: Users need to pass in the co-ordinates separated by comma.
3. Location Type: A query parameter to indicate API returns results for precise addresses or approximate.
4. Result Type : A query parameter to indicate results needed either for a street address, establishment amongst other options that are available in the API docs.

Required Output Extractors

1. Full Address: Formatted full address returned by Google.
2. Location Type : Indicator for the kind of location searched for

Getting Distance & Duration

Purpose

1. This function makes a HTTP call to the Distance Matrix API that provides travel distance and time for a matrix of origins and destinations. The API returns information based on the recommended route between start and end points, as calculated by the Google Maps API
2. Leveraging either the full addresses or co-ordinates returned by geocode api to get the travel distance & time between 2 points.

Endpoint & Headers

1. HTTP GET call to the endpoint https://maps.googleapis.com:443//maps/api/distancematrix/json

Required Inputs

The following are the query parameters that are to be passed

1. API Key
2. Origin - Starting Address/ Coordinates
3. Destination - Ending Address/Coordinates
4. Units - Default is metric but imperial could be passed.

Required Outputs

1. Distance : Distance b/w 2 input addresses
2. Duration : Time taken to travel b/w 2 input addresses.

Getting Distance & Duration with parameters

Purpose

1. This function is used exactly in the same manner as the previously described connector function however we are passing additional query parameters to obtain the results.
2. Driving is a default mode of transport when Distance Matrix API returns the duration & distance result between 2 locations. If there is a use case for getting the results using different modes of transport like Rail, Subway or walking, we could leverage google's additional query parameters to obtain the desired data.

Endpoint & Headers

1. HTTP GET call to the endpoint https://maps.googleapis.com:443//maps/api/distancematrix/json

Required Inputs

The following are the query parameters that are to be passed

1. API Key
2. Origin - Starting Address/ Coordinates
3. Destination - Ending Address/Coordinates
4. Units - Default is metric but imperial could be passed.
5. Mode of Travel: To specify a different mode other than the default mode being driving
6. Transit Mode: A sub mode of travel within the parent mode. (Rail/Subway under Transit)

Required Outputs

1. Distance : Distance b/w 2 input addresses
2. Duration : Time taken to travel b/w 2 input addresses.