thejourneyplanner.integrations package

Submodules

thejourneyplanner.integrations.geocoding module

geocoding.py: Integration with the Geocoder API.

thejourneyplanner.integrations.geocoding.extract_address_place_id(data: dict[str, Any]) → list[tuple[str, str]]

Extracts a list of tuples containing addresses and place IDs from the API response.

Parameters:

data (dict[str, Any]) – The response data from the Place Autocomplete API.

Returns:

A list of tuples where each tuple contains the address and the corresponding place ID.

Return type:

List[Tuple[str, str]]

thejourneyplanner.integrations.geocoding.get_current_location() → tuple[float, float]

Get the current geographical location of the user based on their IP address.

Returns:

A tuple containing the latitude and longitude of the current location. If the location cannot be determined, returns (None, None).

Return type:

tuple[float, float]

Raises:

ValueError – If the location cannot be determined.

Examples

>>> lat, lon = get_current_location()
>>> print(lat, lon)
(37.7749, -122.4194)
thejourneyplanner.integrations.geocoding.get_latitude_longitude(api_key: str, location: str) → tuple[float, float]

Get the latitude and longitude of a location using the Place Autocomplete API.

Parameters:

  • api_key (str) – The API key for the Google Maps API.

  • location (str) – The location to get the latitude and longitude for.

Returns:

A tuple containing the latitude and longitude of the location.

Return type:

tuple[float, float]

Notes

Uses the Place Autocomplete API to get the latitude and longitude of a location. It asks the user to select the correct location if multiple results are found.

thejourneyplanner.integrations.google_maps module

google_maps.py: Integration with the Google Maps API.

thejourneyplanner.integrations.google_maps.compute_route(api_key: str, origin_latlong: tuple[float, float], destination_latlong: tuple[float, float], intermediate_latlongs: list[tuple[float, float]] = [], travel_mode: str = 'DRIVE', routing_preference: str = 'TRAFFIC_AWARE', compute_alternative_routes: bool = False, avoid_tolls: bool = False, avoid_highways: bool = False, avoid_ferries: bool = False, units: Literal['IMPERIAL', 'METRIC'] = 'METRIC') → dict[str, Any]

Compute a route between two locations using the Google Routes API.

Parameters:

  • api_key (str) – The API key for authenticating requests to the Google Maps API.

  • origin_latlong (tuple of float) – The latitude and longitude of the origin location.

  • destination_latlong (tuple of float) – The latitude and longitude of the destination location.

  • intermediate_latlongs (list of tuple of float, optional) – A list of intermediate locations to visit along the route. Default is [].

  • travel_mode (str, optional) – Mode of travel (e.g., ‘DRIVE’, ‘WALK’). Default is ‘DRIVE’.

  • routing_preference (str, optional) – Routing preference (e.g., ‘TRAFFIC_AWARE’). Default is ‘TRAFFIC_AWARE’.

  • compute_alternative_routes (bool, optional) – Whether to compute alternative routes. Default is False.

  • avoid_tolls (bool, optional) – Whether to avoid tolls. Default is False.

  • avoid_highways (bool, optional) – Whether to avoid highways. Default is False.

  • avoid_ferries (bool, optional) – Whether to avoid ferries. Default is False.

  • units (Literal['IMPERIAL', 'METRIC'], optional) – Units for the response. Default is ‘METRIC’.

Returns:

A dictionary containing the route distance, duration, and encoded polyline.

Return type:

dict of str to int or str

Raises:

ValueError – If the API request fails or if the response contains an error.

Example

>>> api_key = 'your_api_key_here'
>>> origin_lat = 37.419734
>>> origin_lng = -122.0827784
>>> destination_lat = 37.417670
>>> destination_lng = -122.079595
>>> compute_route(api_key, (origin_lat, origin_lng), (destination_lat, destination_lng))
{
    'distance_meters': 772,
    'duration_seconds': 165,
    'encoded_polyline': 'ipkcFfichVnP@j@BLoFVwM{E?'
}
thejourneyplanner.integrations.google_maps.place_autocomplete(api_key: str, input_text: str, components: str | None = None, language: str | None = 'en-GB', location: str | None = None, radius: float | None = None, offset: int | None = None, origin: str | None = None, region: str | None = None, session_token: str | None = None, strict_bounds: bool | None = None, types: str | None = None) → dict[str, Any]

Interacts with the Google Place Autocomplete API (New) to retrieve place predictions.

Parameters:

  • api_key (str) – Your API key for accessing the Google Places API.

  • input_text (str) – The text string on which to search. The Place Autocomplete service will return candidate matches based on this string.

  • components (str, optional) – A grouping of places to restrict results (e.g., ‘country:fr’).

  • language (str, optional) – The language in which to return results.

  • location (str, optional) – The point around which to retrieve place information, specified as ‘latitude,longitude’.

  • radius (float, optional) – Defines the distance (in meters) within which to return place results.

  • offset (int, optional) – The position of the last character that the service uses to match predictions.

  • origin (str, optional) – The origin point from which to calculate straight-line distance to the destination.

  • region (str, optional) – The region code, specified as a ccTLD (e.g., ‘uk’).

  • session_token (str, optional) – A random string which identifies an autocomplete session for billing purposes.

  • strict_bounds (bool, optional) – Returns only those places that are strictly within the region defined by location and radius.

  • types (str, optional) – Restrict results to a certain type (e.g., ‘establishment|geocode’).

Returns:

A dictionary containing the predictions and status of the request.

Return type:

Dict[str, Any]

Raises:

ValueError – If the API request fails or if the response contains an error.

thejourneyplanner.integrations.google_maps.search_nearby_places(api_key: str, latlong: tuple[float, float], radius: float, types_list: list[str] = ['tourist_attraction']) → list[dict[str, Any]]

Search for nearby places using the Google Places API.

Parameters:

  • api_key (str) – The API key for authenticating requests to the Google Maps API.

  • latlong (tuple of float) – The latitude and longitude of the search location.

  • radius (float) – The radius of the search area in meters.

  • types_list (list of str, optional) – A list of place types to include in the search. Default is Constants.NEARBY_SEARCH_TYPES.

Returns:

A list of dictionaries containing information about the nearby places.

Return type:

list of dict of str to Any

Raises:

ValueError – If the API request fails or if the response contains an error.

Example

>>> api_key = 'your_api_key_here'
>>> latitude = 52.2635809
>>> longitude = 0.6916481
>>> radius = 10000
>>> search_nearby_places(api_key, (latitude, longitude), radius)
[
    {
        'formatted_address': 'West Midland Safari and Leisure Park, Bewdley DY12 1LF, UK',
        'rating': 4.5,
        'user_rating_count': 2,
        'display_name': 'Twilight Cave'
    },
    ...
]

Note

Search radius is limited to 50000 meters (50 km) by the API. Hence, the maximum value for the radius parameter is 50000 meters. If it’s larger then the function will cap it at 50000 meters and raise a warning.

Module contents

Integrations package for the project.