add get_provider_by_id for consistency, enhance get_provider_info

CHANGELOG.md

@@ -8,6 +8,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+- New `get_provider_by_id()` method that follows the naming convention of other provider search methods
+
+### Changed
+- Enhanced `get_provider_info()` to be the central provider search implementation:
+  - Now accepts optional search parameters: `provider_id`, `country_code`, and `name`
+  - Returns either a single provider (when searching by ID) or a list of providers (when searching by country or name)
+  - Powers all other provider search methods internally for better consistency
+  - Improved error handling and CSV fallback behavior
+
 ## [0.4.0] - 2024-12-27
 
 ### Added

docs/api-reference/client.md

@@ -65,6 +65,12 @@ class DatasetMetadata:
 # Function signatures
 def get_providers_by_country(country_code: str) -> List[Dict]: ...
 def get_providers_by_name(name: str) -> List[Dict]: ...
+def get_provider_by_id(provider_id: str) -> Optional[Dict]: ...
+def get_provider_info(
+    provider_id: Optional[str] = None,
+    country_code: Optional[str] = None,
+    name: Optional[str] = None
+) -> Union[Optional[Dict], List[Dict]]: ...
 def download_latest_dataset(
     provider_id: str,
     download_dir: Optional[str] = None,
@@ -258,6 +264,65 @@ api = MobilityAPI()
 providers = api.get_providers_by_name("BKK")
 ```
 
+#### get_provider_by_id
+```python
+get_provider_by_id(provider_id: str) -> Optional[Dict]
+```
+Get information about a specific provider by ID.
+
+Parameters:
+- `provider_id`: The unique identifier of the provider
+
+Returns:
+- Dictionary containing provider information and downloaded dataset details if available
+- None if the provider doesn't exist or is inactive/deprecated
+
+Example:
+```python
+api = MobilityAPI()
+info = api.get_provider_by_id("mdb-123")
+if info:
+    print(f"Provider: {info['provider']}")
+    if 'downloaded_dataset' in info:
+        print(f"Downloaded: {info['downloaded_dataset']['download_path']}")
+```
+
+#### get_provider_info
+```python
+get_provider_info(
+    provider_id: Optional[str] = None,
+    country_code: Optional[str] = None,
+    name: Optional[str] = None
+) -> Union[Optional[Dict], List[Dict]]
+```
+Get information about providers based on search criteria. This method combines the functionality
+of `get_provider_by_id`, `get_providers_by_country`, and `get_providers_by_name` into a single method.
+
+Parameters:
+- `provider_id`: Optional provider ID for exact match
+- `country_code`: Optional two-letter ISO country code for filtering
+- `name`: Optional provider name for partial matching
+
+Returns:
+- If `provider_id` is specified:
+  - Dictionary containing provider information and downloaded dataset details if available
+  - None if the provider doesn't exist or is inactive/deprecated
+- If `country_code` or `name` is specified:
+  - List of matching provider dictionaries
+- If no criteria specified:
+  - Empty list
+
+Example:
+```python
+api = MobilityAPI()
+# Get by ID
+info = api.get_provider_info(provider_id="mdb-123")
+# Get by country
+be_providers = api.get_provider_info(country_code="BE")
+# Get by name
+sncb = api.get_provider_info(name="SNCB")
+```
+
 #### download_latest_dataset
 ```python
 download_latest_dataset(provider_id: str, 

docs/examples.md

@@ -7,20 +7,34 @@ from mobility_db_api import MobilityAPI
 
 api = MobilityAPI()
 
-# Search by country
+# Search by country (traditional way)
 providers = api.get_providers_by_country("BE")
 print(f"Found {len(providers)} providers in Belgium")
 
-# Search by name
+# Search by name (traditional way)
 sncb = api.get_providers_by_name("SNCB")
 print(f"Found {len(sncb)} SNCB providers")
 
-# Print provider details
-if providers:
-    provider = providers[0]
+# Get provider by ID (new way)
+provider = api.get_provider_by_id("mdb-123")
+if provider:
+    print(f"Found provider: {provider['provider']}")
+
+# Combined search functionality (new way)
+# Search by country
+be_providers = api.get_provider_info(country_code="BE")
+print(f"Found {len(be_providers)} providers in Belgium")
+
+# Search by name
+sncb = api.get_provider_info(name="SNCB")
+print(f"Found {len(sncb)} SNCB providers")
+
+# Get by ID with downloaded dataset info
+provider = api.get_provider_info(provider_id="mdb-123")
+if provider:
     print(f"Provider: {provider['provider']}")
-    print(f"ID: {provider['id']}")
-    print(f"Direct download: {'Yes' if provider.get('direct_download_url') else 'No'}")
+    if 'downloaded_dataset' in provider:
+        print(f"Downloaded dataset: {provider['downloaded_dataset']['download_path']}")
 ```
 
 ## Dataset Download