Source code for plantpredict.geo

import json
import requests
from plantpredict.utilities import convert_json, camel_to_snake, decorate_all_methods
from plantpredict.error_handlers import handle_refused_connection, handle_error_response


[docs]@decorate_all_methods(handle_refused_connection) @decorate_all_methods(handle_error_response) class Geo(object): """ The :py:mod:`Geo` entity is used to get location-related information for a given latitude/longitude. Its methods can be used individually, but typically location related info is needed in the context of a PlantPredict :py:mod:`Project` entity. In this case the user can simply call the method :py:meth:`Project.get_location_info` which calls all :py:mod:`Geo` class methods and automatically assigns all location-related attributes to that instance of :py:mod:`Project`. Note: This API resource does not represent a database entity in PlantPredict. This is a simplified connection to the Google Maps API. See Google Maps API Reference for further functionality. (https://developers.google.com/maps/) """ def get_location_info(self): """ **GET** */Geo/* :py:attr:`latitude` */* :py:attr:`longitude` */Location* Retrieves pertinent location info for a given latitude and longitude such as locality, state/province, country, etc. In addition to returning a dictionary with this information, the method also automatically assigns the contents of the dictionary to the instance of :py:mod:`Geo` as attributes. .. container:: toggle .. container:: header **Required Attributes** .. container:: required_attributes .. csv-table:: Minimum required attributes on object to call this method successfully. :delim: ; :header: Field, Type, Description :stub-columns: 1 latitude; float; North-South GPS coordinate. Must be between :py:data:`-90` and :py:data:`90` - units :py:data:`[decimal degrees]`. longitude; float; East-West GPS coordinate Must be between :py:data:`-180` and :py:data:`180` units :py:data:`[decimal degrees]`. .. container:: toggle .. container:: header **Example Code** .. container:: example_code Instantiate a local object instance of :py:mod:`Geo` with latitude and longitude as inputs (which automatically assigns them as attributes to the object). Then call the method on the object. .. code-block:: python geo = api.geo(latitude=35.1, longitude=-106.7) geo.get_location_info() .. container:: toggle .. container:: header **Example Response** .. container:: example_response The method returns a dictionary as shown in the example below, and assigns its contents as attributes to the local object instance of :py:mod:`Geo`. .. code-block:: python { "country": "United States", "country_code": "US", "locality": "Albuquerque", "region": "North America", "state_province": "New Mexico", "state_province_code": "NM } :return: A dictionary with location information as shown in "Example Response". :rtype: dict """ response = requests.get( url=self.api.base_url + "/Geo/{}/{}/Location".format(self.latitude, self.longitude), headers={"Authorization": "Bearer " + self.api.access_token} ) attr = convert_json(json.loads(response.content), camel_to_snake) for key in attr: setattr(self, key, attr[key]) return response def get_elevation(self): """ **GET** */Geo/* :py:attr:`latitude` */* :py:attr:`longitude` */Elevation* Retrieves the elevation in meters for a given latitude and longitude. In addition to returning a dictionary with this information, the method also automatically assigns the contents of the dictionary to the instance of :py:mod:`Geo` as attributes. .. container:: toggle .. container:: header **Required Attributes** .. container:: required_attributes .. csv-table:: Minimum required attributes on object to call this method successfully. :delim: ; :header: Field, Type, Description :stub-columns: 1 latitude; float; North-South GPS coordinate. Must be between :py:data:`-90` and :py:data:`90` - units :py:data:`[decimal degrees]`. longitude; float; East-West GPS coordinate Must be between :py:data:`-180` and :py:data:`180` units :py:data:`[decimal degrees]`. .. container:: toggle .. container:: header **Example Code** .. container:: example_code Instantiate a local object instance of :py:mod:`Geo` with latitude and longitude as inputs (which automatically assigns them as attributes to the object). Then call the method on the object. .. code-block:: python geo = api.geo(latitude=35.1, longitude=-106.7) geo.get_elevation() .. container:: toggle .. container:: header **Example Response** .. container:: example_response The method returns a dictionary as shown in the example below, and assigns its contents as attributes to the local object instance of :py:mod:`Geo`. .. code-block:: python { "elevation": 1553.614 } :return: A dictionary with location information as shown in "Example Response". :rtype: dict """ response = requests.get( url=self.api.base_url + "/Geo/{}/{}/Elevation".format(self.latitude, self.longitude), headers={"Authorization": "Bearer " + self.api.access_token} ) attr = convert_json(json.loads(response.content), camel_to_snake) for key in attr: setattr(self, key, attr[key]) return response def get_time_zone(self): """ **GET** */Geo/* :py:attr:`latitude` */* :py:attr:`longitude` */TimeZone* Retrieves the time zone as a time shift in hours with respect to GMT for a given latitude and longitude. In addition to returning a dictionary with this information, the method also automatically assigns the contents of the dictionary to the instance of :py:mod:`Geo` as attributes. .. container:: toggle .. container:: header **Required Attributes** .. container:: required_attributes .. csv-table:: Minimum required attributes on object to call this method successfully. :delim: ; :header: Field, Type, Description :stub-columns: 1 latitude; float; North-South GPS coordinate. Must be between :py:data:`-90` and :py:data:`90` - units :py:data:`[decimal degrees]`. longitude; float; East-West GPS coordinate Must be between :py:data:`-180` and :py:data:`180` units :py:data:`[decimal degrees]`. .. container:: toggle .. container:: header **Example Code** .. container:: example_code Instantiate a local object instance of :py:mod:`Geo` with latitude and longitude as inputs (which automatically assigns them as attributes to the object). Then call the method on the object. .. code-block:: python geo = api.geo(latitude=35.1, longitude=-106.7) geo.get_time_zone() .. container:: toggle .. container:: header **Example Response** .. container:: example_response The method returns a dictionary as shown in the example below, and assigns its contents as attributes to the local object instance of :py:mod:`Geo`. .. code-block:: python { "time_zone": -7.0 } :return: A dictionary with location information as shown in "Example Response". :rtype: dict """ response = requests.get( url=self.api.base_url + "/Geo/{}/{}/TimeZone".format(self.latitude, self.longitude), headers={"Authorization": "Bearer " + self.api.access_token} ) attr = convert_json(json.loads(response.content), camel_to_snake) for key in attr: setattr(self, key, attr[key]) return response def __init__(self, api, latitude=None, longitude=None): """ Initializes a local object instance of :py:mod:`Geo`. :param api: :py:class:`~plantpredict.api.Api` object. :type api: object :param latitude: North-South GPS coordinate. Must be between :py:data:`-90` and :py:data:`90` - units :py:data:`[decimal degrees]`. :type latitude: float :param longitude: East-West GPS coordinate Must be between :py:data:`-180` and :py:data:`180` units :py:data:`[decimal degrees]`. :type longitude: float """ self.api = api self.latitude = latitude self.longitude = longitude super(Geo, self).__init__()