feat(documentation): add more documentations

README.md

@@ -6,25 +6,6 @@ This repository provides a unofficial Python wrapper to use [navitia.io APIs](ht
 
 To use this library, you will need an access token from [navitia.io](https://navitia.io/tarifs/).
 
-##  Installation
-
-The package is not yet available on pip.
-
-For development purpose, you can install it using
-
-```bash
-pip install -e .
-```
-
-## Usage
-
-```python
-from navitia_client.client import NavitiaClient
-client = NavitiaClient(auth=<YOUR_TOKEN_HERE>)
-```
-
-A base URL for Navitia IO is hardcoded and provided to NavitiaClient by default. It can be updated using the base_navitia_url parameter.
-
 ##  API support
 
 The library supports the following [APIs](https://doc.navitia.io/#api-catalog):
@@ -50,6 +31,51 @@ The library supports the following [APIs](https://doc.navitia.io/#api-catalog):
 | Traffic reports                           | ✅           | Beta endpoint according to API response      |
 | Equipment reports                         | ❌           | Beta service, not available to all providers |
 
+##  Installation
+
+The package is not yet available on pip.
+
+For development purpose, you can install it using
+
+```bash
+pip install -e .
+```
+
+## Usage
+
+To use this library, you need an authentication token provided by Navitia.io.
+
+### Create client instance
+
+Once created, you will create an instance of the NavitiaClient class with the following:
+
+```python
+from navitia_client.client import NavitiaClient
+client = NavitiaClient(auth=<YOUR_TOKEN_HERE>)
+```
+
+A base URL for Navitia IO is hardcoded and provided to NavitiaClient by default. It can be updated using the base_navitia_url parameter.
+
+###  Access APIs data
+
+URLs are mapped as property in the class `NavitiaClient`. You can find the mapping [here](docs/api_support/).
+
+For example, if you want to have the list of datasets in a given region, use:
+
+```python
+datasets, pagination = client.datasets.list_datasets(region_id=<REGION_ID>)
+```
+
+### Pagination
+
+A couple of APIs are paginated, in particular the public transporations APIs.. In such case, you can navigate in the response using the parameters `start_page` and `count`.
+
+An object `Pagination` will be provided by the impacted methods to help you navigatig.
+
+### Tips
+
+Few tips on how to use the Navitia APIs are available [here](docs/few_tips.md)
+
 ##  Dependencies
 
 * Python >= 3.10

docs/api_support/commercial_modes.md

@@ -0,0 +1,59 @@
+# Commercial modes
+
+API client for handling 'CommercialMode' entities in the Navitia API.
+
+Official documentation: <https://doc.navitia.io/#pt-ref>
+
+Property: `NavitiaClient.commercial_modes`
+
+Methods:
+
+```python
+        list_entity_collection_from_region(
+            region_id: str,
+            start_page: int = 0,
+            count: int = 25,
+            depth: int = 1,
+            odt: str = "all",
+            distance: int = 200,
+            headsign: Optional[str] = None,
+        ) -> Tuple[Sequence[CommercialMode], Pagination]:
+            Lists commercial modes from a specified region.
+
+        get_entity_by_id(
+            region_id: str,
+            object_id: str,
+            start_page: int = 0,
+            count: int = 25,
+            depth: int = 1,
+            odt: str = "all",
+            distance: int = 200,
+            headsign: Optional[str] = None,
+        ) -> Tuple[Sequence[CommercialMode], Pagination]:
+            Retrieves a specific commercial mode by its ID from a specified region.
+
+        list_entity_collection_from_coordinates(
+            lon: float,
+            lat: float,
+            start_page: int = 0,
+            count: int = 25,
+            depth: int = 1,
+            odt: str = "all",
+            distance: int = 200,
+            headsign: Optional[str] = None,
+        ) -> Tuple[Sequence[CommercialMode], Pagination]:
+            Lists commercial modes from specified coordinates.
+
+        get_entity_by_id_and_coordinates(
+            lon: float,
+            lat: float,
+            object_id: str,
+            start_page: int = 0,
+            count: int = 25,
+            depth: int = 1,
+            odt: str = "all",
+            distance: int = 200,
+            headsign: Optional[str] = None,
+        ) -> Tuple[Sequence[CommercialMode], Pagination]:
+            Retrieves a specific commercial mode by its ID from specified coordinates.
+```

docs/api_support/companies.md

@@ -0,0 +1,59 @@
+#   Companies
+
+API client for handling 'Company' entities in the Navitia API.
+
+Official documentation: <https://doc.navitia.io/#pt-ref>
+
+Property: `NavitiaClient.companies`
+
+Methods:
+
+```python
+    list_entity_collection_from_region(
+        region_id: str,
+        start_page: int = 0,
+        count: int = 25,
+        depth: int = 1,
+        odt: str = "all",
+        distance: int = 200,
+        headsign: Optional[str] = None
+    ) -> Tuple[Sequence[Company], Pagination]:
+        List companies for a given region.
+
+    get_entity_by_id(
+        region_id: str,
+        object_id: str,
+        start_page: int = 0,
+        count: int = 25,
+        depth: int = 1,
+        odt: str = "all",
+        distance: int = 200,
+        headsign: Optional[str] = None
+    ) -> Tuple[Sequence[Company], Pagination]:
+        Get a company by its ID in a given region.
+
+    list_entity_collection_from_coordinates(
+        lon: float,
+        lat: float,
+        start_page: int = 0,
+        count: int = 25,
+        depth: int = 1,
+        odt: str = "all",
+        distance: int = 200,
+        headsign: Optional[str] = None
+    ) -> Tuple[Sequence[Company], Pagination]:
+        List companies for given geographic coordinates.
+
+    get_entity_by_id_and_coordinates(
+        lon: float,
+        lat: float,
+        object_id: str,
+        start_page: int = 0,
+        count: int = 25,
+        depth: int = 1,
+        odt: str = "all",
+        distance: int = 200,
+        headsign: Optional[str] = None
+    ) -> Tuple[Sequence[Company], Pagination]:
+        Get a company by its ID for given geographic coordinates.
+```

docs/api_support/contributors.md

@@ -0,0 +1,18 @@
+# Contributors
+
+A client class to interact with the Navitia API for fetching contributors APIs.
+
+Official documentation: <https://doc.navitia.io/#contributors>
+
+Property: `NavitiaClient.contributors`
+
+Methods:
+
+```python
+
+    list_contributors(region_id: str, start_page: int = 0, count: int = 25) -> Tuple[Sequence[Contributor], Pagination]
+        Retrieves a list of contributors for a specified region from the Navitia API.
+
+    get_contributor_on_dataset(region_id: str, dataset_id: str, start_page: int = 0, count: int = 25) -> Tuple[Sequence[Contributor], Pagination]
+        Retrieves a list of contributors for a specified dataset in a region from the Navitia API.
+```

docs/api_support/coverage.md

@@ -0,0 +1,21 @@
+#  Coverage
+
+A client class to interact with the Navitia API for fetching coverage area information.
+
+Official documentation: <https://doc.navitia.io/#coverage>
+
+Property: `NavitiaClient.coverage`
+
+
+Methods:
+
+```python
+    list_covered_areas(start_page: int = 0, count: int = 25) -> Tuple[Sequence[Region], Pagination]
+        Retrieves a list of covered areas from the Navitia API.
+
+    get_coverage_by_region_id(region_id: str, start_page: int = 0, count: int = 25) -> Tuple[Sequence[Region], Pagination]
+        Retrieves information about a specific region by its ID.
+
+    get_coverage_by_region_coordinates_and_coordinates(lon: float, lat: float, start_page: int = 0, count: int = 25) -> Tuple[Sequence[Region], Pagination]
+        Retrieves information about a region based on coordinates.
+```

docs/api_support/datasets.md

@@ -0,0 +1,18 @@
+# Datasets
+
+A client class to interact with the Navitia API for fetching dataset information.
+
+Official documentation: <https://doc.navitia.io/#datasets>
+
+Property: `NavitiaClient.datasets`
+
+Methods:
+
+```python
+    list_datasets(region_id: str, start_page: int = 0, count: int = 25) -> Tuple[Sequence[Dataset], Pagination]
+        Retrieves a list of datasets for a specified region from the Navitia API.
+
+    get_dataset_by_id(region_id: str, dataset_id: str, start_page: int = 0, count: int = 25) -> Tuple[Sequence[Dataset], Pagination]
+        Retrieves information about a specific dataset by its ID within a region.
+    """
+```

docs/api_support/departures.md

@@ -0,0 +1,40 @@
+# Vehicle journeys
+
+A client class to interact with the Navitia API for fetching departure information.
+
+Official documentation: <https://doc.navitia.io/#departures>
+
+Property: `NavitiaClient.departures`
+
+Methods
+
+```python
+
+    list_departures_by_region_id_and_path(
+        region_id: str,
+        resource_path: str,
+        from_datetime: datetime = datetime.now(),
+        duration: int = 86400,
+        depth: int = 1,
+        forbidden_uris: Optional[Sequence[str]] = None,
+        data_freshness: str = "realtime",
+        disable_geojson: bool = False,
+        direction_type: str = "all"
+    ) -> Tuple[Sequence[Departure], Pagination]
+        Retrieves a list of departures for a specified region and resource path from the Navitia API.
+
+    list_departures_by_coordinates(
+        region_lon: float,
+        region_lat: float,
+        lon: float,
+        lat: float,
+        from_datetime: datetime = datetime.now(),
+        duration: int = 86400,
+        depth: int = 1,
+        forbidden_uris: Optional[Sequence[str]] = None,
+        data_freshness: str = "realtime",
+        disable_geojson: bool = False,
+        direction_type: str = "all"
+    ) -> Tuple[Sequence[Departure], Pagination]
+        Retrieves a list of departures for a specified location based on coordinates from the Navitia API.
+```

docs/api_support/disruptions.md

@@ -0,0 +1,60 @@
+# Disruptions
+
+API client for handling 'Disruption' entities in the Navitia API.
+
+official documentation: <https://doc.navitia.io/#pt-ref>
+
+Property: `NavitiaClient.disruptions`
+
+Methods:
+
+```python
+
+    list_entity_collection_from_region(
+        region_id: str,
+        start_page: int = 0,
+        count: int = 25,
+        depth: int = 1,
+        odt: str = "all",
+        distance: int = 200,
+        headsign: Optional[str] = None
+    ) -> Tuple[Sequence[Disruption], Pagination]:
+        List disruptions for a given region.
+
+    get_entity_by_id(
+        region_id: str,
+        object_id: str,
+        start_page: int = 0,
+        count: int = 25,
+        depth: int = 1,
+        odt: str = "all",
+        distance: int = 200,
+        headsign: Optional[str] = None
+    ) -> Tuple[Sequence[Disruption], Pagination]:
+        Get a disruption by its ID in a given region.
+
+    list_entity_collection_from_coordinates(
+        lon: float,
+        lat: float,
+        start_page: int = 0,
+        count: int = 25,
+        depth: int = 1,
+        odt: str = "all",
+        distance: int = 200,
+        headsign: Optional[str] = None
+    ) -> Tuple[Sequence[Disruption], Pagination]:
+        List disruptions for given geographic coordinates.
+
+    get_entity_by_id_and_coordinates(
+        lon: float,
+        lat: float,
+        object_id: str,
+        start_page: int = 0,
+        count: int = 25,
+        depth: int = 1,
+        odt: str = "all",
+        distance: int = 200,
+        headsign: Optional[str] = None
+    ) -> Tuple[Sequence[Disruption], Pagination]:
+        Get a disruption by its ID for given geographic coordinates.
+```

docs/api_support/inverted_geocoding.md

@@ -0,0 +1,30 @@
+# Inverted geocoding
+
+A client class to interact with the Navitia API for performing inverted geocoding operations.
+
+Official documentation: <https://doc.navitia.io/#coord>
+
+Property: `NavitiaClient.inverted_geocoding`
+
+Methods
+
+```python
+
+    get_address_and_region_from_coordinates(lon: float, lat: float) -> Sequence[Place]
+        Retrieves address and region information based on given coordinates.
+
+    get_address_and_region_from_id(id: str) -> Sequence[Place]
+        Retrieves address and region information based on a given place ID.
+
+    get_address_from_region_coordinates_and_coordinates(region_lon: float, region_lat: float, lon: float, lat: float) -> Sequence[Place]
+        Retrieves address information based on region coordinates and specific coordinates.
+
+    get_address_from_region_coordinates_and_id(region_lon: float, region_lat: float, id: str) -> Sequence[Place]
+        Retrieves address information based on region coordinates and a specific place ID.
+
+    get_address_from_region_id_and_coordinates(region_id: str, lon: float, lat: float) -> Sequence[Place]
+        Retrieves address information based on a region ID and specific coordinates.
+
+    get_address_from_region_id_and_id(region_id: str, id: str) -> Sequence[Place]
+        Retrieves address information based on a region ID and a specific place ID.
+```