Skip to content

Client module

Source code in geobatchpy/client.py 
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
class Client:

    def __init__(self, api_key: str):
        self._api_key = get_api_key(api_key=api_key)
        self.batch = BatchClient(api_key=api_key)
        self.boundaries = BoundariesClient(api_key=api_key)
        self._headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
        self._logger = logging.getLogger(__name__)

    def places(self, categories: Union[str, List[str]], filter_by_region: str = None,
               filter_by_name: str = None, proximity_by: Tuple[float, float] = None,
               conditions: Union[str, List[str]] = None, limit: int = 20, offset: int = None,
               language: str = None) -> dict:
        """Query locations of different categories.

        See the Geoapify API documentation for a full list of categories and any other supported parameters.

        Arguments:
            categories: returned places must be in one of the chosen categories.
            filter_by_region: places must be within boundaries of the specified geometry.
            filter_by_name: places' names are used for filtering.
            proximity_by: (lon, lat) tuple; places will be returned in order of proximity to the coordinates.
            conditions: places must fulfill all of the provided conditions.
            limit: maximal number of places returned.
            offset: return next places by starting counting from `offset`.
            language: iso code of the language in which places should be returned.

        Returns:
            List of places encoded in JSON like dictionaries.
        """
        request_url = get_api_url(api=API_PLACES, api_key=self._api_key)
        params = dict()
        if isinstance(categories, str):
            params['categories'] = categories
        else:
            params['categories'] = ','.join(categories)
        if filter_by_region is not None:
            params['filter'] = filter_by_region
        if filter_by_name is not None:
            params['name'] = filter_by_name
        if proximity_by is not None:
            params['bias'] = f'proximity:{proximity_by[0]},{proximity_by[1]}'
        if isinstance(conditions, str):
            params['conditions'] = conditions
        elif conditions is not None:
            params['conditions'] = ','.join(conditions)

        params['limit'] = limit
        params['offset'] = offset
        if language is not None:
            params['lang'] = language

        return requests.get(url=request_url, params=params, headers=self._headers).json()

    def place_details(self, place_id: str = None, longitude: float = None, latitude: float = None,
                      features: List[str] = None, language: str = None) -> dict:
        """Returns place details of a location.

        Use either the `place_id` (returned by geocoding) or geo coordinates to specify a location. The `features`
        argument specifies which kind of details to request. See the geoapify.com documentation.

        Arguments:
            place_id: the Nominatim place_id as a string.
            latitude: float or string representing latitude.
            longitude: float or string representing longitude.
            features: list of types of details. Defaults to just ["details"] if not specified.
            language: 2-character iso language code.

        Returns:
            Structured location details.
        """
        request_url = get_api_url(api=API_PLACE_DETAILS, api_key=self._api_key)
        params = dict()
        if place_id is not None:
            params['id'] = place_id
        elif latitude is not None and longitude is not None:
            params['lat'] = str(latitude)
            params['lon'] = str(longitude)
        else:
            raise ValueError('Either place_id or latitude and longitude must be provided.')
        if features is not None:
            params['features'] = ','.join(features)
        if language is not None:
            params['lang'] = language

        return requests.get(url=request_url, params=params, headers=self._headers).json()

    def geocode(self, text: str = None, parameters: Dict[str, str] = None) -> dict:
        """Returns geocoding results as a dictionary.

        Use either a free text search wit the `text` argument or alternatively provide input in a structured
        form using the `parameters` argument. See the geoapify.com API documentation.

        Arguments:
            text: free text search of a location.
            parameters: structured search as key value pairs and other optional parameters.

        Returns:
            Structured, geocoded, and enriched address record.
        """
        request_url = get_api_url(api=API_GEOCODE, api_key=self._api_key)

        params = {'text': text} if text is not None else dict()
        if parameters is not None:
            params = {**params, **parameters}

        return requests.get(url=request_url, params=params, headers=self._headers).json()

    def reverse_geocode(self, longitude: float, latitude: float) -> dict:
        """Returns reverse geocoding results as a dictionary.

        Arguments:
            latitude: float representing latitude.
            longitude: float representing longitude.

        Returns:
            Structured, reverse geocoded, and enriched address record.
        """
        request_url = get_api_url(api=API_REVERSE_GEOCODE, api_key=self._api_key)
        params = {'lat': str(latitude), 'lon': str(longitude)}

        return requests.get(url=request_url, params=params, headers=self._headers).json()

    def isoline(self, longitude: float, latitude: float, travel_range: int,
                travel_mode: str = 'drive', isoline_type: str = 'time', output_format: str = 'geojson') -> dict:
        """Returns isoline results as a dictionary.

        Args:
            longitude: float representing longitude.
            latitude: float representing latitude.
            travel_range: either travel time in seconds or travel distance in meters, depending on `isoline_type`.
            travel_mode: one of the many supported 'mode's - see the Geoapify API docs.
            isoline_type: either 'time' or 'distance'.
            output_format: one of 'geojson', 'topojson', 'geobuf'.

        Returns:
            Structured isoline details.
        """
        request_url = get_api_url(api=API_ISOLINE, api_key=self._api_key)
        params = {'lon': str(longitude), 'lat': str(latitude), 'range': travel_range, 'mode': travel_mode,
                  'type': isoline_type, 'format': output_format}
        return requests.get(url=request_url, params=params, headers=self._headers).json()

    def route_matrix(self, source_geocodes: List[Tuple[float, float]],
                     target_geocodes: List[Tuple[float, float]] = None,
                     travel_mode: str = 'drive', ) -> dict:
        """Returns route matrix results as a dictionary.

        `target_geocodes = None` translates to `target_geocodes = source_geocodes`.

        Args:
            source_geocodes: list of (lon, lat) tuples of source locations.
            target_geocodes: list of (lon, lat) tuples of target locations or None.
            travel_mode: one of 'drive', 'truck', 'walk', 'bicycle'.

        Returns:

        """
        request_url = get_api_url(api=API_ROUTE_MATRIX, api_key=self._api_key)
        if target_geocodes is None:
            target_geocodes = source_geocodes
        data = {
            'mode': travel_mode,
            'sources': [{'location': geocode} for geocode in source_geocodes],
            'targets': [{'location': geocode} for geocode in target_geocodes]
        }
        return requests.post(url=request_url, json=data, headers=self._headers).json()

__init__(api_key)

Source code in geobatchpy/client.py 
19
20
21
22
23
24
def __init__(self, api_key: str):
    self._api_key = get_api_key(api_key=api_key)
    self.batch = BatchClient(api_key=api_key)
    self.boundaries = BoundariesClient(api_key=api_key)
    self._headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
    self._logger = logging.getLogger(__name__)

places(categories, filter_by_region=None, filter_by_name=None, proximity_by=None, conditions=None, limit=20, offset=None, language=None)

Query locations of different categories.

See the Geoapify API documentation for a full list of categories and any other supported parameters.

Parameters:

Name Type Description Default
categories Union[str, List[str]]

returned places must be in one of the chosen categories.

 required
filter_by_region str

places must be within boundaries of the specified geometry.

 None
filter_by_name str

places' names are used for filtering.

 None
proximity_by Tuple[float, float]

(lon, lat) tuple; places will be returned in order of proximity to the coordinates.

 None
conditions Union[str, List[str]]

places must fulfill all of the provided conditions.

 None
limit int

maximal number of places returned.

 20
offset int

return next places by starting counting from offset.

 None
language str

iso code of the language in which places should be returned.

 None

Returns:

Type Description
dict

List of places encoded in JSON like dictionaries.
Source code in geobatchpy/client.py 
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
def places(self, categories: Union[str, List[str]], filter_by_region: str = None,
           filter_by_name: str = None, proximity_by: Tuple[float, float] = None,
           conditions: Union[str, List[str]] = None, limit: int = 20, offset: int = None,
           language: str = None) -> dict:
    """Query locations of different categories.

    See the Geoapify API documentation for a full list of categories and any other supported parameters.

    Arguments:
        categories: returned places must be in one of the chosen categories.
        filter_by_region: places must be within boundaries of the specified geometry.
        filter_by_name: places' names are used for filtering.
        proximity_by: (lon, lat) tuple; places will be returned in order of proximity to the coordinates.
        conditions: places must fulfill all of the provided conditions.
        limit: maximal number of places returned.
        offset: return next places by starting counting from `offset`.
        language: iso code of the language in which places should be returned.

    Returns:
        List of places encoded in JSON like dictionaries.
    """
    request_url = get_api_url(api=API_PLACES, api_key=self._api_key)
    params = dict()
    if isinstance(categories, str):
        params['categories'] = categories
    else:
        params['categories'] = ','.join(categories)
    if filter_by_region is not None:
        params['filter'] = filter_by_region
    if filter_by_name is not None:
        params['name'] = filter_by_name
    if proximity_by is not None:
        params['bias'] = f'proximity:{proximity_by[0]},{proximity_by[1]}'
    if isinstance(conditions, str):
        params['conditions'] = conditions
    elif conditions is not None:
        params['conditions'] = ','.join(conditions)

    params['limit'] = limit
    params['offset'] = offset
    if language is not None:
        params['lang'] = language

    return requests.get(url=request_url, params=params, headers=self._headers).json()

geocode(text=None, parameters=None)

Returns geocoding results as a dictionary.

Use either a free text search wit the text argument or alternatively provide input in a structured form using the parameters argument. See the geoapify.com API documentation.

Parameters:

Name Type Description Default
text str

free text search of a location.

 None
parameters Dict[str, str]

structured search as key value pairs and other optional parameters.

 None

Returns:

Type Description
dict

Structured, geocoded, and enriched address record.
Source code in geobatchpy/client.py 
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
def geocode(self, text: str = None, parameters: Dict[str, str] = None) -> dict:
    """Returns geocoding results as a dictionary.

    Use either a free text search wit the `text` argument or alternatively provide input in a structured
    form using the `parameters` argument. See the geoapify.com API documentation.

    Arguments:
        text: free text search of a location.
        parameters: structured search as key value pairs and other optional parameters.

    Returns:
        Structured, geocoded, and enriched address record.
    """
    request_url = get_api_url(api=API_GEOCODE, api_key=self._api_key)

    params = {'text': text} if text is not None else dict()
    if parameters is not None:
        params = {**params, **parameters}

    return requests.get(url=request_url, params=params, headers=self._headers).json()

reverse_geocode(longitude, latitude)

Returns reverse geocoding results as a dictionary.

Parameters:

Name Type Description Default
latitude float

float representing latitude.

 required
longitude float

float representing longitude.

 required

Returns:

Type Description
dict

Structured, reverse geocoded, and enriched address record.
Source code in geobatchpy/client.py 
125
126
127
128
129
130
131
132
133
134
135
136
137
138
def reverse_geocode(self, longitude: float, latitude: float) -> dict:
    """Returns reverse geocoding results as a dictionary.

    Arguments:
        latitude: float representing latitude.
        longitude: float representing longitude.

    Returns:
        Structured, reverse geocoded, and enriched address record.
    """
    request_url = get_api_url(api=API_REVERSE_GEOCODE, api_key=self._api_key)
    params = {'lat': str(latitude), 'lon': str(longitude)}

    return requests.get(url=request_url, params=params, headers=self._headers).json()