Add Python map, geocoding and reverse geocoding code samples

Author: Alfiya Tarasenko

README.md

@@ -6,7 +6,7 @@ Welcome to the **Geoapify Location Platform Code Samples** repository! This proj
 
 ## Available Code Samples
 
-### **1. Printable Route Directions (Available Now)**
+### **1. JavaScript: Printable Route Directions**
 
 #### Description:
 This code sample demonstrates how to generate **Printable Route Directions** using Geoapify's Routing API and Static Maps API with JavaScript and HTML. It includes interactive features and static content generation for detailed route instructions.
@@ -24,6 +24,46 @@ This code sample demonstrates how to generate **Printable Route Directions** usi
 #### Demo:
 Explore the demo: [Printable Route Directions Demo](https://geoapify.github.io/maps-api-code-samples/javascript/printable-route-directions/demo.html)
 
+
+### **2. Python: Create Map Example**
+
+#### Description:
+This sample demonstrates how to generate an interactive map using the Geoapify Maps API with Python and Folium.
+
+#### Features:
+- Custom map styles using Geoapify API.
+- Interactive markers for enhanced user experience.
+- Dynamic zoom and center capabilities.
+
+#### APIs Used:
+- [Geoapify Maps Tiles](https://www.geoapify.com/map-tiles/)
+
+### **3. Python: Batch Geocode Example**
+
+#### Description:
+This example shows how to perform forward geocoding using the Geoapify Geocoding API to obtain latitude and longitude from addresses.
+
+#### Features:
+- Batch geocoding support.
+- Country filtering for improved accuracy.
+- NDJSON output format.
+
+#### APIs Used:
+- [Geoapify Geocoding API](https://www.geoapify.com/geocoding-api/)
+
+### **4. Python: Reverse Geocode Example**
+
+#### Description:
+This example demonstrates how to perform reverse geocoding to retrieve addresses from latitude and longitude coordinates using the Geoapify API.
+
+#### Features:
+- Batch processing of coordinates.
+- Configurable response format (`json` or `geojson`).
+- Country filtering for improved results.
+
+#### APIs Used:
+- [Geoapify Reverse Geocoding API](https://www.geoapify.com/reverse-geocoding-api/)
+
 ---
 
 ## Upcoming Code Samples

javascript/.DS_Store

@@ -0,0 +1,156 @@
+# Python Interactive Map Example
+
+This project demonstrates how to use the [Geoapify Maps Tiles](https://www.geoapify.com/map-tiles/) to display an interactive raster map using [folium](https://pypi.org/project/folium/). The map includes customizable styles, zoom levels, and center coordinates.
+
+---
+
+## **Features**
+- Uses Geoapify Maps API for high-quality map tiles.
+- Supports various map styles.
+- Allows customization of zoom level and map center.
+- Displays an interactive map with an Eiffel Tower marker.
+- Automatically validates API keys and handles errors.
+
+![Route Preview on a Map](https://github.com/geoapify/maps-api-code-samples/blob/main/python/create-a-map/map.png?raw=true)
+
+## **Requirements**
+
+Ensure you have the following installed:
+
+1. Python 3.11 or higher
+2. pip (Python package manager)
+
+## **Setup Instructions**
+
+### 1. Clone the Repository
+
+```bash
+git clone https://geoapify.github.io/maps-api-code-samples/
+cd maps-api-code-samples/python
+```
+
+### 2. Create a Virtual Environment (Optional)
+
+It’s recommended to use a virtual environment to avoid dependency conflicts:
+
+```bash
+python -m venv env
+source env/bin/activate  # On Windows: env\Scripts\activate
+```
+
+### 3. Install Dependencies
+
+Install the required Python libraries using pip:
+
+```bash
+pip install folium requests
+```
+
+---
+
+## **Running the Example**
+
+Run the script to generate an interactive map:
+
+```bash
+cd create-a-map
+python interactive_map.py --style osm-bright --zoom 12 --lat 48.8566 --lon 2.3522 --api-key=YOUR_API_KEY
+```
+
+### **Command-line Arguments**
+- `--api-key` (required): API key for Geoapify services.
+- `--style` (optional, default: `osm-carto`): Map style.
+- `--zoom` (optional, default: `17`): Zoom level.
+- `--lat` (optional, default: `48.8584`): Latitude for the map center.
+- `--lon` (optional, default: `2.2945`): Longitude for the map center.
+
+---
+
+## Code Explanation
+
+The `create_map` function initializes an interactive map using `folium`. It takes the map style, zoom level, latitude, longitude, and API key as parameters to generate a customized map with Geoapify tiles.
+
+```python
+import folium
+
+BASE_URL = "https://maps.geoapify.com/v1/tile/{map_style}/{{z}}/{{x}}/{{y}}@2x.png?apiKey={api_key}"
+
+def create_map(map_style, zoom, lat, lon, api_key):
+    """
+    Creates an interactive map using Geoapify tiles.
+
+    Parameters:
+    - map_style (str): The style of the map (e.g., 'osm-carto', 'osm-bright').
+    - zoom (int): The initial zoom level.
+    - lat (float): Latitude for the map center.
+    - lon (float): Longitude for the map center.
+    - api_key (str): API key for accessing Geoapify services.
+
+    Returns:
+    - folium.Map object containing the configured map.
+    """
+
+    # Initialize the folium map centered at the specified location
+    m = folium.Map(location=[lat, lon], zoom_start=zoom)
+
+    # Construct the tile layer URL using the provided API key and map style
+    tile_url = BASE_URL.format(map_style=map_style, api_key=api_key)
+
+    # Add Geoapify tile layer to the map
+    folium.TileLayer(
+        tiles=tile_url,
+        name="Geoapify Map",
+        attr="""Powered by <a href="https://www.geoapify.com/" target="_blank">Geoapify</a> 
+                | <a href="https://openmaptiles.org/" rel="nofollow" target="_blank">© OpenMapTiles</a> 
+                | <a href="https://www.openstreetmap.org/copyright" rel="nofollow" target="_blank">© OpenStreetMap</a> contributors""",
+        overlay=True,
+        control=True
+    ).add_to(m)
+
+    # Add a marker at the Eiffel Tower location for demonstration purposes
+    folium.Marker(
+        location=[48.8584, 2.2945],
+        popup="Eiffel Tower",
+        icon=folium.Icon(color="red"),
+    ).add_to(m)
+
+    return m
+```
+
+### **Explanation**
+1. **Initialize the Map**  
+   - Uses `folium.Map()` to create a base map centered at the provided latitude and longitude.
+   - The `zoom_start` parameter determines the initial zoom level.
+
+2. **Add Tile Layer**  
+   - The tile layer URL is formatted using the provided `map_style` and `api_key` values.
+   - The tile layer is added using `folium.TileLayer()`, ensuring that Geoapify map styles are applied.
+
+3. **Add a Marker**  
+   - A red marker is placed at the Eiffel Tower's coordinates (`48.8584, 2.2945`).
+   - The marker has a popup message that appears when clicked.
+
+4. **Return the Map**  
+   - The function returns a `folium.Map` object that can be saved as an HTML file or displayed in a browser.
+
+This function allows users to create a customizable interactive map with Geoapify tiles, supporting different styles and zoom levels.
+
+---
+
+## **Output**
+- The script generates a `map.html` file.
+- The browser automatically opens the generated map.
+- If the browser fails to open, manually open `map.html` in any web browser.
+
+## **Error Handling**
+- If an invalid map style is provided, the script falls back to `osm-carto`.
+- If an invalid API key is provided, the script exits with an error.
+- If a server error occurs (5XX response), the script stops execution.
+
+## **Notes**
+- Ensure that you have a valid [Geoapify API key](https://www.geoapify.com/) before running the script.
+- The map includes attribution links to comply with OpenStreetMap and Geoapify usage policies.
+
+## **License**
+This project is licensed under the MIT License.
+

python/create-a-map/README.md

@@ -0,0 +1,101 @@
+"""
+This script generates an interactive map using the Geoapify Maps API and displays it in a web browser using folium.
+
+Dependencies:
+- folium
+- requests
+
+To install the required libraries, run:
+pip install folium requests
+
+Usage:
+python interactive_map.py --style osm-bright --zoom 12 --lat 48.8566 --lon 2.3522 --api-key=your-api-key
+
+Command-line arguments:
+--api-key: Api Key for Geoapify services
+--style: Map style (default: osm-carto)
+--zoom: Zoom level (default: 17)
+--lat: Latitude for the map center (default: 48.8584)
+--lon: Longitude for the map center (default: 2.2945)
+"""
+
+import argparse
+import sys
+import webbrowser
+
+import folium
+import requests
+
+# Define base URL for Geoapify
+BASE_URL = "https://maps.geoapify.com/v1/tile/{map_style}/{{z}}/{{x}}/{{y}}@2x.png?apiKey={api_key}"
+
+
+def create_map(map_style, zoom, lat, lon, api_key) -> folium.Map:
+    # Create a folium map centered at the given latitude and longitude
+    m = folium.Map(location=[lat, lon], zoom_start=zoom)
+
+    # Construct the tile URL with the selected map style and API Key
+    tile_url = BASE_URL.format(map_style=map_style, api_key=api_key)
+
+    # Add the Geoapify raster tiles to the map
+    folium.TileLayer(
+        tiles=tile_url,
+        name='Geoapify Map',
+        attr="""Powered by <a href="https://www.geoapify.com/" target="_blank">Geoapify</a> 
+        | <a href="https://openmaptiles.org/" rel="nofollow" target="_blank">© OpenMapTiles</a> 
+        <a href="https://www.openstreetmap.org/copyright" rel="nofollow" target="_blank">© OpenStreetMap</a> contributors""",
+        overlay=True,
+        control=True
+    ).add_to(m)
+
+    # Add Eiffel Tower pin to the map
+    folium.Marker(
+        location=[48.8584, 2.2945],
+        popup='Eiffel Tower',
+        icon=folium.Icon(color='red'),
+    ).add_to(m)
+
+    # Return the map object
+    return m
+
+
+def get_arg_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(description='Generate an interactive map using Geoapify Maps API.')
+    parser.add_argument('--style', type=str, default='osm-carto', help='Map style (default: osm-carto)')
+    parser.add_argument('--zoom', type=int, default=17, help='Zoom level (default: 17)')
+    parser.add_argument('--lat', type=float, default=48.8584, help='Latitude for the map center (default: 48.8584)')
+    parser.add_argument('--lon', type=float, default=2.2945, help='Longitude for the map center (default: 2.2945)')
+    parser.add_argument('--api-key', type=str, required=True, help='Api Key for Geoapify services')
+
+    return parser
+
+
+def main():
+    # Set up argument parsing for command-line customization
+    parser = get_arg_parser()
+    args = parser.parse_args()
+
+    # Validate the map style by making a request to the Geoapify API
+    response = requests.get(BASE_URL.format(map_style=args.style,
+                                            api_key=args.api_key).replace('{z}/{x}/{y}', '0/0/0'))
+    if response.status_code == 400:
+        print(f"Error: Possible issue with incorrect map style. Falling back to default 'osm-carto'.")
+        args.style = 'osm-carto'
+    elif response.status_code == 401:
+        print('Invalid Api Key, abort')
+        sys.exit(1)
+    elif response.status_code // 100 == 5:
+        print('Server respond with 5XX error, abort')
+        sys.exit(1)
+
+    # Create the map with the specified parameters
+    map_object = create_map(args.style, args.zoom, args.lat, args.lon, args.api_key)
+
+    # Better not to use show_in_browser method as it can lead to file not found error in different os
+    map_object.save('map.html')
+    if not webbrowser.open('map.html'):
+        print('Cannot open default browser, check your settings')
+
+
+if __name__ == "__main__":
+    main()