API Documentation

Main Classes

GoogleMaps class

class gomaps.GoogleMaps(query: str, fields=[], session=None)

A response object from a Google Maps request

This class is initialized with a search string (query) and returns the result of the query. It also resolves the new redirected Google Maps URL.

Parameters:
  • q (str) – A search string that’s assigned to the ‘?q=’ URL argument.
  • fields (list) – Specify which data points to scrape.
  • session (requests_html.HTMLSession) – An HTMLSession object from the requests_html Python package.
Returns:

A single GoogleMaps object already containing the queried place’s url, title, and lat/long coordinates
oq

The original query string

query

The URL string that a request was sent to. (example: 'https://www.google.com/maps?q=Tops+Diner')

title

The title or name of the place found (available upon initialization)

url

The newly redirected URL of the place on Google Maps (available upon initialization)

coordinates

The lattitude and longitude coordinates of the place store in tuple. (ex: ('40.7506065', '-74.1639023') (available upon initialization)

coords

Alternative for referencing ‘coordinates’ attribute

address

The full address of the place

phone_number

The phone number (otherwise returns None)

website

The website (otherwise returns None)

rating

The star rating ranging from 0.0-5.0 (otherwise returns None)

open_hours

The open hours of operation of the place. Returns a dictionary.

popular_times

The Google Maps Popular Times data for 7 days of the week. Returns a dictionary.

values

Returns a dictionary with all the attributes of the place listed above. (Note: Only populated after get_values() member function is called)

get_values()

This sends an additional request, populates the rest of the attributes, then returns a Python dictionary of all the attributes.

Tip

The GoogleMaps object’s attributes can be accessed via the dot operator or key indexing. (ex: result[coords] or result.coords)

GoogleMapsResults class

class gomaps.GoogleMapsResults(query: str, page_num=1, delay=10, log=False)

A response object containing GoogleMaps objects as a result of the request

This class is initialized with a search string (query) and returns the result(s) within a list-like object.

Parameters:
  • query (str) – A search string that’s assigned to the ‘?q=’ URL argument.
  • page_num (int) – The number refering to the page of results to be web scraped.
  • delay (int) – An integer specifying the time in seconds to wait after each request.
  • log (bool) – If True, prints the places’ GoogleMaps object as they’re discovered.
Returns:

A list-like object containing GoogleMaps objects as a result of the query.
oq

The original query string

query

The URL string that a request was sent to. (example: 'https://www.google.com/search?q=Tops+Diner')

url

The newly redirected URL of the place on Google Maps (available upon initialization as long as there’s only a single result)

delay

The number specifying the time in seconds to wait after each request.

list()

Returns the GoogleMapsResults object as an actual Python list

Main Functions

Searches for a place(s) on Google Maps & returns the results

Parameters:
  • q – The query string used to search Google Maps.
  • page_num – The number refering to the page of the results to be web scraped.
  • delay – The number specifying the time in seconds to wait after each request.
  • log – If True, prints the found results as they occur.
  • single – If True, only returns the single GoogleMaps object directly.
  • fields – If single=True, specify which data points to scrape.

Warning

delay cannot be less than 5 seconds, otherwise bot will be detected and blocked for too many requests

Returns:

Returns a GoogleMapsResults object containing GoogleMaps objects from the search
Example:
>>> results = gomaps.maps_search("Tops Diner")
>>> place = results[0].get_values()
>>> place.rating
4.6

Tip

The following functions are overloaded. That being said the functions with data as a parameter can take an HTML string as input for data as well as a normal query string.

gomaps.geocoder(location: str, reverse: bool=False)

Searches for the lattitude & longitude coordinates of a location. Reverse geocoding searches for the location of coordinates

Parameters:
  • location – A place name, address or lat/long coordinates
  • reverse – If True, uses reverse geocoder

Note

This function doesn’t scrape everything. As a result, it is especially lightweight as opposed to using maps_search

Returns:

Returns a tuple of lat/long coordinates or address of the location if reverse=True’’’
Example:
>>> result = gomaps.geocoder("Tops Diner")
>>> result
('40.7506065', '-74.1639023')
gomaps.get_url(data: str)

Searches for full Google Maps URL of a location

Parameters:data – A place name, address or lat/long coordinates
Returns:Returns a string of the redirected URL
gomaps.get_title(data: str)

Searches for the title or name of a location

Parameters:data – A place name, address or lat/long coordinates
Returns:Returns a string of the location’s title
gomaps.get_address(data: str, validate: bool=False)

Searches for the full address of a location

Parameters:
  • data – A place name, address or lat/long coordinates
  • validate – If True, attempts to validate address
Returns:

Returns a string of the location’s address
gomaps.get_website(data: str)

Searches for the website (if any) of a location

Parameters:data – A place name
Returns:Returns a string of the location’s website
gomaps.get_phone_number(data: str)

Searches for the phone number (if any) of a location

Parameters:data – A place name
Returns:Returns a string of the location’s phone number
gomaps.get_rating(data: str)

Searches for the rating (if any) of a location

Parameters:data – A place name
Returns:Returns a float of the location’s rating
get_open_hours(data: str)

Searches for the open hours (if any) of a location

Parameters:data – A place name
Returns:Returns a string of the location’s open hours

Searches for the Google Maps popular times (if any) of a location

Parameters:data – A place name, address, lat/long coordinates or HTML
Returns:Returns a list of the location’s popular times