docs: update README with verified examples and installation instructions

- Replace fictional addresses with real, valid addresses (White House, Apple HQ)

- Fix List API examples to use correct .data attribute for paginated responses

- Add working error handling examples with proper exception types

- Update development installation instructions to use -e flag

- Improve code examples to show actual output rather than raw objects

- All examples tested and verified to work with live API

Author: funkatron

README.md

@@ -29,14 +29,13 @@ Development Installation
 
 2. Create and activate a virtual environment:
     ```bash
-    python -m .venv venv
-    source .venv/bin/activate  # On Windows: venv\Scripts\activate
+    python -m venv venv
+    source venv/bin/activate  # On Windows: venv\Scripts\activate
     ```
 
 3. Install development dependencies:
     ```bash
-    pip install .
-    pip install .[dev]
+    pip install -e .
     pip install -r requirements-dev.txt
     ```
 
@@ -52,27 +51,28 @@ from geocodio import GeocodioClient
 client = GeocodioClient("YOUR_API_KEY")
 
 # Single forward geocode
-response = client.geocode("123 Anywhere St, Chicago, IL")
-print(response)
+response = client.geocode("1600 Pennsylvania Ave, Washington, DC")
+print(response.results[0].formatted_address)
 
 # Batch forward geocode
 addresses = [
-    "123 Anywhere St, Chicago, IL",
-    "456 Oak St, Los Angeles, CA"
+    "1600 Pennsylvania Ave, Washington, DC",
+    "1 Infinite Loop, Cupertino, CA"
 ]
 batch_response = client.geocode(addresses)
-print(batch_response)
+for result in batch_response.results:
+    print(result.formatted_address)
 
 # Single reverse geocode
 rev = client.reverse("38.9002898,-76.9990361")
-print(rev)
+print(rev.results[0].formatted_address)
 
 # Append additional fields
 data = client.geocode(
-    "123 Anywhere St, Chicago, IL",
+    "1600 Pennsylvania Ave, Washington, DC",
     fields=["cd", "timezone"]
 )
-print(data)
+print(data.results[0].fields.timezone.name if data.results[0].fields.timezone else "No timezone data")
 ```
 
 ### List API
@@ -85,68 +85,50 @@ from geocodio import GeocodioClient
 # Initialize the client with your API key
 client = GeocodioClient("YOUR_API_KEY")
 
-# Create a new list
-new_list = client.create_list(
-    name="My Addresses",
-    description="A list of addresses to geocode",
-    items=[
-        "1600 Pennsylvania Ave, Washington, DC",
-        "1 Infinite Loop, Cupertino, CA"
-    ]
-)
-print(new_list)
-
 # Get all lists
 lists = client.get_lists()
-print(lists)
+print(f"Found {len(lists.data)} lists")
 
-# Get a specific list
-list_id = new_list.list.id
-list_details = client.get_list(list_id)
-print(list_details)
-
-# Update a list
-updated_list = client.update_list(
-    list_id=list_id,
-    name="Updated List Name",
-    description="Updated description"
-)
-print(updated_list)
-
-# Add items to a list
-added_items = client.add_items_to_list(
-    list_id=list_id,
-    items=[
-        "123 Anywhere St, Chicago, IL",
-        "456 Oak St, Los Angeles, CA"
-    ]
-)
-print(added_items)
+# Create a new list from a file
+with open("addresses.csv", "rb") as f:
+    new_list = client.create_list(
+        file=f,
+        filename="addresses.csv",
+        direction="forward"
+    )
+print(f"Created list: {new_list.id}")
 
-# Geocode all items in a list
-geocoded_list = client.geocode_list(
-    list_id=list_id,
-    fields=["timezone", "cd"]
-)
-print(geocoded_list)
+# Get a specific list
+list_details = client.get_list(new_list.id)
+print(f"List status: {list_details.status}")
 
-# Remove items from a list
-item_ids = [item.id for item in added_items.items]
-client.remove_items_from_list(
-    list_id=list_id,
-    item_ids=item_ids
-)
+# Download a completed list
+if list_details.status and list_details.status.get("state") == "COMPLETED":
+    file_content = client.download(new_list.id, "downloaded_results.csv")
+    print("List downloaded successfully")
 
 # Delete a list
-client.delete_list(list_id)
+client.delete_list(new_list.id)
 ```
 
 Error Handling
 --------------
 
-- `GeocodioAuthError` is raised for authentication failures (HTTP 403).
-- `GeocodioDataError` is raised for invalid requests (HTTP 422).
-- `GeocodioServerError` is raised for server-side errors (HTTP 5xx).
+```python
+from geocodio import GeocodioClient, AuthenticationError, InvalidRequestError
+
+try:
+    client = GeocodioClient("INVALID_API_KEY")
+    response = client.geocode("1600 Pennsylvania Ave, Washington, DC")
+except AuthenticationError as e:
+    print(f"Authentication failed: {e}")
+
+try:
+    client = GeocodioClient("YOUR_API_KEY")
+    response = client.geocode("")  # Empty address
+except InvalidRequestError as e:
+    print(f"Invalid request: {e}")
+```
 
 Documentation
 -------------