diff --git a/README.md b/README.md index 23ad63b..71d2cc8 100644 --- a/README.md +++ b/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=) -``` - -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=) +``` + +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=) +``` + +### 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 diff --git a/docs/api_support/commercial_modes.md b/docs/api_support/commercial_modes.md new file mode 100644 index 0000000..e631580 --- /dev/null +++ b/docs/api_support/commercial_modes.md @@ -0,0 +1,59 @@ +# Commercial modes + +API client for handling 'CommercialMode' entities in the Navitia API. + +Official documentation: + +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. +``` diff --git a/docs/api_support/companies.md b/docs/api_support/companies.md new file mode 100644 index 0000000..b676c2a --- /dev/null +++ b/docs/api_support/companies.md @@ -0,0 +1,59 @@ +#   Companies + +API client for handling 'Company' entities in the Navitia API. + +Official documentation: + +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. +``` diff --git a/docs/api_support/contributors.md b/docs/api_support/contributors.md new file mode 100644 index 0000000..c81783d --- /dev/null +++ b/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: + +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. +``` diff --git a/docs/api_support/coverage.md b/docs/api_support/coverage.md new file mode 100644 index 0000000..98b6951 --- /dev/null +++ b/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: + +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. +``` diff --git a/docs/api_support/datasets.md b/docs/api_support/datasets.md new file mode 100644 index 0000000..b9ef789 --- /dev/null +++ b/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: + +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. + """ +``` diff --git a/docs/api_support/departures.md b/docs/api_support/departures.md new file mode 100644 index 0000000..2738104 --- /dev/null +++ b/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: + +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. +``` diff --git a/docs/api_support/disruptions.md b/docs/api_support/disruptions.md new file mode 100644 index 0000000..80ba3bf --- /dev/null +++ b/docs/api_support/disruptions.md @@ -0,0 +1,60 @@ +# Disruptions + +API client for handling 'Disruption' entities in the Navitia API. + +official documentation: + +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. +``` diff --git a/docs/api_support/inverted_geocoding.md b/docs/api_support/inverted_geocoding.md new file mode 100644 index 0000000..1c350e5 --- /dev/null +++ b/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: + +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. +``` diff --git a/docs/api_support/isochrones.md b/docs/api_support/isochrones.md new file mode 100644 index 0000000..6e8f233 --- /dev/null +++ b/docs/api_support/isochrones.md @@ -0,0 +1,37 @@ +# Isochrones + +A client class to interact with the Navitia API for performing inverted geocoding operations. + +Official documentation: + +Property: `NavitiaClient.isochrones` + +Methods + +```python + + list_isochrones_with_region_id( + from_: str, + region_id: str, + start_datetime: datetime = datetime.now(), + boundary_duration: Sequence[int] = [], + to: Optional[str] = None, + first_section_mode: Optional[Sequence[str]] = None, + last_section_mode: Optional[Sequence[str]] = None, + min_duration: Optional[int] = None, + max_duration: Optional[int] = None + ) -> Sequence[Isochrone] + Fetches isochrones data for a specific region based on various parameters. + + list_isochrones( + from_: str, + start_datetime: datetime = datetime.now(), + boundary_duration: Sequence[int] = [], + to: Optional[str] = None, + first_section_mode: Optional[Sequence[str]] = None, + last_section_mode: Optional[Sequence[str]] = None, + min_duration: Optional[int] = None, + max_duration: Optional[int] = None + ) -> Sequence[Isochrone] + Fetches isochrones data based on various parameters. +``` diff --git a/docs/api_support/journeys.md b/docs/api_support/journeys.md new file mode 100644 index 0000000..06548f8 --- /dev/null +++ b/docs/api_support/journeys.md @@ -0,0 +1,121 @@ +# Journeys + +A client class to interact with the Navitia API for fetching journey data. + +Official documentation: + +Property: `NavitiaClient.journeys` + +Methods + +```python + + list_journeys( + from_: Optional[str] = None, + to_: Optional[str] = None, + datetime_: datetime = datetime.now(), + datetime_represents: str = "departure", + traveler_type: str = "standard", + data_freshness: str = "realtime", + forbidden_uris: Optional[Sequence[str]] = None, + allowed_id: Optional[Sequence[str]] = None, + first_section_mode: Optional[Sequence[str]] = None, + last_section_mode: Optional[Sequence[str]] = None, + language: str = "en-GB", + depth: int = 1, + max_duration_to_pt: int = 30 * 60, + walking_speed: float = 1.12, + bike_speed: float = 4.1, + bss_speed: float = 4.1, + car_speed: float = 16.8, + min_nb_journeys: int = 1, + max_nb_journeys: int = 1, + count: int = 1, + max_nb_transfers: int = 10, + min_nb_transfers: int = 0, + max_duration: int = 86400, + wheelchair: bool = False, + direct_path: str = "indifferent", + direct_path_mode: Optional[Sequence[str]] = None, + add_poi_infos: Sequence[str] = [], + debug: bool = False, + free_radius_from: int = 0, + free_radius_to: int = 0, + timeframe_duration: int = 0 + ) -> Sequence[Journey] + Fetches journey data based on various parameters. + + list_journeys_with_region_id( + self, + region_id: str, + from_: Optional[str] = None, + to_: Optional[str] = None, + datetime_: datetime = datetime.now(), + datetime_represents: str = "departure", + traveler_type: str = "standard", + data_freshness: str = "realtime", + forbidden_uris: Optional[Sequence[str]] = None, + allowed_id: Optional[Sequence[str]] = None, + first_section_mode: Optional[Sequence[str]] = None, + last_section_mode: Optional[Sequence[str]] = None, + language: str = "en-GB", + depth: int = 1, + max_duration_to_pt: int = 30 * 60, + walking_speed: float = 1.12, + bike_speed: float = 4.1, + bss_speed: float = 4.1, + car_speed: float = 16.8, + min_nb_journeys: int = 1, + max_nb_journeys: int = 1, + count: int = 1, + max_nb_transfers: int = 10, + min_nb_transfers: int = 0, + max_duration: int = 86400, + wheelchair: bool = False, + direct_path: str = "indifferent", + direct_path_mode: Optional[Sequence[str]] = None, + add_poi_infos: Sequence[str] = [], + debug: bool = False, + free_radius_from: int = 0, + free_radius_to: int = 0, + timeframe_duration: int = 0 + ) -> Sequence[Journey] + Fetches journey data for a specific region based on various parameters. + + list_journeys_with_resource_path( + self, + resource_path: str, + from_: Optional[str] = None, + to_: Optional[str] = None, + datetime_: datetime = datetime.now(), + datetime_represents: str = "departure", + traveler_type: str = "standard", + data_freshness: str = "realtime", + forbidden_uris: Optional[Sequence[str]] = None, + allowed_id: Optional[Sequence[str]] = None, + first_section_mode: Optional[Sequence[str]] = None, + last_section_mode: Optional[Sequence[str]] = None, + language: str = "en-GB", + depth: int = 1, + max_duration_to_pt: int = 30 * 60, + walking_speed: float = 1.12, + bike_speed: float = 4.1, + bss_speed: float = 4.1, + car_speed: float = 16.8, + min_nb_journeys: int = 1, + max_nb_journeys: int = 1, + count: int = 1, + max_nb_transfers: int = 10, + min_nb_transfers: int = 0, + max_duration: int = 86400, + wheelchair: bool = False, + direct_path: str = "indifferent", + direct_path_mode: Optional[Sequence[str]] = None, + add_poi_infos: Sequence[str] = [], + debug: bool = False, + free_radius_from: int = 0, + free_radius_to: int = 0, + timeframe_duration: int = 0 + ) -> Sequence[Journey] + Fetches journey data for a specific resource path based on various parameters. +``` diff --git a/docs/api_support/line_reports.md b/docs/api_support/line_reports.md new file mode 100644 index 0000000..f5e1870 --- /dev/null +++ b/docs/api_support/line_reports.md @@ -0,0 +1,24 @@ +# Line reports + +A client class to interact with the Navitia API for fetching line reports. + +Official documentation: + +Property: `NavitiaClient.line_reports` + +Methods + +```python + + list_line_reports( + region_id: Optional[str] = None, + resource_path: Optional[str] = None, + since: Optional[datetime] = None, + until: Optional[datetime] = None, + count: int = 25, + depth: int = 1, + forbidden_uris: Optional[Sequence[str]] = None, + disable_geojson: bool = False + ) -> Tuple[Sequence[Disruption], Sequence[LineReport]]: + Lists line reports based on specified criteria. +``` diff --git a/docs/api_support/lines.md b/docs/api_support/lines.md new file mode 100644 index 0000000..0532306 --- /dev/null +++ b/docs/api_support/lines.md @@ -0,0 +1,60 @@ +# Lines + +API client for handling 'Line' entities in the Navitia API. + +Official documentation: + +Property: `NavitiaClient.lines` + +Methods: + +```python3 + + 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[Line], Pagination]: + List lines 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[Line], Pagination]: + Get a line 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[Line], Pagination]: + List lines 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[Line], Pagination]: + Get a line by its ID for given geographic coordinates. +``` diff --git a/docs/api_support/networks.md b/docs/api_support/networks.md new file mode 100644 index 0000000..775e39d --- /dev/null +++ b/docs/api_support/networks.md @@ -0,0 +1,59 @@ +#  Networks + +API client for handling 'Network' entities in the Navitia API. + +Official documentation: + +Property: `NavitiaClient.networks` + +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[Network], Pagination]: + List networks 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[Network], Pagination]: + Get a network 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[Network], Pagination]: + List networks 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[Network], Pagination]: + Get a network by its ID for given geographic coordinates. +``` diff --git a/docs/api_support/physical_modes.md b/docs/api_support/physical_modes.md new file mode 100644 index 0000000..54c45d8 --- /dev/null +++ b/docs/api_support/physical_modes.md @@ -0,0 +1,59 @@ +# Physical modes + +API client for handling 'PhysicalMode' entities in the Navitia API. + +Official documentation: + +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[PhysicalMode], Pagination]: + List physical modes 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[PhysicalMode], Pagination]: + Get a physical mode 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[PhysicalMode], Pagination]: + List physical modes 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[PhysicalMode], Pagination]: + Get a physical mode by its ID for given geographic coordinates. +``` diff --git a/docs/api_support/places.md b/docs/api_support/places.md new file mode 100644 index 0000000..9c7e7c1 --- /dev/null +++ b/docs/api_support/places.md @@ -0,0 +1,20 @@ +# Places + +A client class to interact with the Navitia API for fetching place information. + +Official documentation: + +Property: `NavitiaClient.places` + +Methods + +```python + + list_places( + region_id: str, query: str, + type: Sequence[str] = ["stop_area", "address", "poi", "administrative_region"], + disable_geojson: bool = False, depth: int = 1, + from_lon_lat: Optional[Tuple[float, float]] = None + ) -> Sequence[Place] + Retrieves a list of places based on the provided query and region ID from the Navitia API. +``` diff --git a/docs/api_support/places_nearby.md b/docs/api_support/places_nearby.md new file mode 100644 index 0000000..a2874e5 --- /dev/null +++ b/docs/api_support/places_nearby.md @@ -0,0 +1,53 @@ +# Places nearby + +A client class to interact with the Navitia API for fetching nearby places information. + +Official documentation: + +Property: `NavitiaClient.places_nearby` + +Methods + +```python + + list_objects_by_region_id_and_path( + region_id: str, resource_path: str, + distance: int = 500, type: Sequence[str] = ["stop_area", "stop_point", "poi"], + admin_uri: Optional[Sequence[str]] = None, filter: Optional[str] = None, + disable_geojson: bool = False, disable_disruption: bool = False, + depth: int = 1, start_page: int = 0, count: int = 25, + add_poi_infos: Sequence[str] = ["bss_stands", "car_park"] + ) -> Tuple[Sequence[Place], Pagination] + Retrieves a list of places nearby based on the region ID and resource path from the Navitia API. + + list_objects_by_region_id_and_coordinates( + region_id: str, lon: float, lat: float, + distance: int = 500, type: Sequence[str] = ["stop_area", "stop_point", "poi"], + admin_uri: Optional[Sequence[str]] = None, filter: Optional[str] = None, + disable_geojson: bool = False, disable_disruption: bool = False, + depth: int = 1, start_page: int = 0, count: int = 25, + add_poi_infos: Sequence[str] = ["bss_stands", "car_park"] + ) -> Tuple[Sequence[Place], Pagination] + Retrieves a list of places nearby based on the region ID and coordinates from the Navitia API. + + list_objects_by_coordinates( + region_lon: float, region_lat: float, lon: float, lat: float, + distance: int = 500, type: Sequence[str] = ["stop_area", "stop_point", "poi"], + admin_uri: Optional[Sequence[str]] = None, filter: Optional[str] = None, + disable_geojson: bool = False, disable_disruption: bool = False, + depth: int = 1, start_page: int = 0, count: int = 25, + add_poi_infos: Sequence[str] = ["bss_stands", "car_park"] + ) -> Tuple[Sequence[Place], Pagination] + Retrieves a list of places nearby based on the coordinates from the Navitia API. + + list_objects_by_object_coordinates_only( + lon: float, lat: float, distance: int = 500, + type: Sequence[str] = ["stop_area", "stop_point", "poi"], + admin_uri: Optional[Sequence[str]] = None, filter: Optional[str] = None, + disable_geojson: bool = False, disable_disruption: bool = False, + depth: int = 1, start_page: int = 0, count: int = 25, + add_poi_infos: Sequence[str] = ["bss_stands", "car_park"] + ) -> Tuple[Sequence[Place], Pagination] + Retrieves a list of places nearby based on the coordinates only from the Navitia API. + +``` diff --git a/docs/api_support/pt_objects.md b/docs/api_support/pt_objects.md new file mode 100644 index 0000000..245b81c --- /dev/null +++ b/docs/api_support/pt_objects.md @@ -0,0 +1,29 @@ +# Public Transport objects + +A client class to interact with the Navitia API for fetching public transport objects. + +Official documentation: + +Property: `NavitiaClient.pt_objects` + +Methods + +```python + + list_public_transport_objects( + region_id: str, + query: str, + type: Sequence[str] = [ + "network", + "commercial_mode", + "line", + "route", + "stop_area", + ], + disable_disruption: bool = False, + depth: int = 1, + post_query_filter: Optional[str] = None, + ) -> Sequence[PtObject]: + Retrieves a list of public transport objects for a specified region from the Navitia API. + +``` diff --git a/docs/api_support/route_schedules.md b/docs/api_support/route_schedules.md new file mode 100644 index 0000000..980c249 --- /dev/null +++ b/docs/api_support/route_schedules.md @@ -0,0 +1,43 @@ +# Route shcedules + +A client class to interact with the Navitia API for fetching route schedules. + +Official documentation: + +Property: `NavitiaClient.route_schedules` + +Methods + +```python + + list_route_schedules_by_region_id_and_path( + region_id: str, + resource_path: str, + from_datetime: datetime = datetime.now(), + duration: int = 86400, + depth: int = 1, + items_per_schedule: int = 1, + forbidden_uris: Optional[Sequence[str]] = None, + data_freshness: str = "base_schedule", + disable_geojson: bool = False, + direction_type: str = "all", + ) -> Sequence[RouteSchedule]: + Retrieves route schedules for a specified region and resource path from the Navitia API. + + list_route_schedules_by_coordinates( + region_lon: float, + region_lat: float, + lon: float, + lat: float, + from_datetime: datetime = datetime.now(), + duration: int = 86400, + depth: int = 1, + items_per_schedule: int = 1, + forbidden_uris: Optional[Sequence[str]] = None, + data_freshness: str = "base_schedule", + disable_geojson: bool = False, + direction_type: str = "all", + ) -> Sequence[RouteSchedule]: + Retrieves route schedules for a specified set of coordinates from the Navitia API. + +``` diff --git a/docs/api_support/routes.md b/docs/api_support/routes.md new file mode 100644 index 0000000..a04d658 --- /dev/null +++ b/docs/api_support/routes.md @@ -0,0 +1,60 @@ +# Routes + +API client for handling 'Route' entities in the Navitia API. + +Official documentation: + +Property: `NavitiaClient.routes` + +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[Route], Pagination]: + List routes 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[Route], Pagination]: + Get a route 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[Route], Pagination]: + List routes 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[Route], Pagination]: + Get a route by its ID for given geographic coordinates. +``` diff --git a/docs/api_support/stop_areas.md b/docs/api_support/stop_areas.md new file mode 100644 index 0000000..0c9b7ac --- /dev/null +++ b/docs/api_support/stop_areas.md @@ -0,0 +1,60 @@ +# Stop areas + +API client for handling 'StopArea' entities in the Navitia API. + +Official documentation: + +Property: `NavitiaClient.stop_areas` + +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[StopArea], Pagination]: + List stop areas 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[StopArea], Pagination]: + Get a stop area 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[StopArea], Pagination]: + List stop areas 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[StopArea], Pagination]: + Get a stop area by its ID for given geographic coordinates. +``` diff --git a/docs/api_support/stop_points.md b/docs/api_support/stop_points.md new file mode 100644 index 0000000..a05a7e1 --- /dev/null +++ b/docs/api_support/stop_points.md @@ -0,0 +1,60 @@ +# Stop points + +API client for handling 'StopPoint' entities in the Navitia API. + +Official documentation: + +Property: `NavitiaClient.stop_points` + +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[StopPoint], Pagination]: + List stop points 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[StopPoint], Pagination]: + Get a stop point 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[StopPoint], Pagination]: + List stop points 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[StopPoint], Pagination]: + Get a stop point by its ID for given geographic coordinates. +``` diff --git a/docs/api_support/stop_schedules.md b/docs/api_support/stop_schedules.md new file mode 100644 index 0000000..4ac4510 --- /dev/null +++ b/docs/api_support/stop_schedules.md @@ -0,0 +1,43 @@ +# Stop schedules + +A client class to interact with the Navitia API for fetching stop schedules. + +Official documentation: + +Property: `NavitiaClient.stop_schedules` + +Methods + +```python + + list_stop_schedules_by_coordinates( + region_lon: float, + region_lat: float, + lon: float, + lat: float, + from_datetime: datetime = datetime.now(), + duration: int = 86400, + depth: int = 1, + items_per_schedule: int = 1, + forbidden_uris: Optional[Sequence[str]] = None, + data_freshness: str = "realtime", + disable_geojson: bool = False, + direction_type: str = "all", + ) -> Tuple[Sequence[StopSchedule], Pagination]: + Retrieves stop schedules for a specified set of coordinates from the Navitia API. + + list_stop_schedules_by_region_id_and_path( + region_id: str, + resource_path: str, + from_datetime: datetime = datetime.now(), + duration: int = 86400, + depth: int = 1, + items_per_schedule: int = 1, + forbidden_uris: Optional[Sequence[str]] = None, + data_freshness: str = "realtime", + disable_geojson: bool = False, + direction_type: str = "all", + ) -> Tuple[Sequence[StopSchedule], Pagination]: + Retrieves stop schedules for a specified region and resource path from the Navitia API. + +``` diff --git a/docs/api_support/terminus_schedules.md b/docs/api_support/terminus_schedules.md new file mode 100644 index 0000000..d196930 --- /dev/null +++ b/docs/api_support/terminus_schedules.md @@ -0,0 +1,43 @@ +# Terminus schedules + +A client class to interact with the Navitia API for fetching terminus schedules. + +Official documentation: + +Property: `NavitiaClient.terminus_schedules` + +Methods + +```python + + list_terminus_schedules_by_region_id_and_path( + region_id: str, + resource_path: str, + from_datetime: datetime = datetime.now(), + duration: int = 86400, + depth: int = 1, + items_per_schedule: int = 1, + forbidden_uris: Optional[Sequence[str]] = None, + data_freshness: str = "realtime", + disable_geojson: bool = False, + direction_type: str = "all", + ) -> Tuple[Sequence[TerminusSchedule], Pagination]: + Retrieves terminus schedules for a specified region and resource path from the Navitia API. + + list_terminus_schedules_by_coordinates( + region_lon: float, + region_lat: float, + lon: float, + lat: float, + from_datetime: datetime = datetime.now(), + duration: int = 86400, + depth: int = 1, + items_per_schedule: int = 1, + forbidden_uris: Optional[Sequence[str]] = None, + data_freshness: str = "realtime", + disable_geojson: bool = False, + direction_type: str = "all", + ) -> Tuple[Sequence[TerminusSchedule], Pagination]: + Retrieves terminus schedules for a specified set of coordinates from the Navitia API. + +``` diff --git a/docs/api_support/traffic_reports.md b/docs/api_support/traffic_reports.md new file mode 100644 index 0000000..8615cb2 --- /dev/null +++ b/docs/api_support/traffic_reports.md @@ -0,0 +1,25 @@ +# Traffic reports + +A client class to interact with the Navitia API for fetching traffic reports. + +Official documentation: + +Property: `NavitiaClient.traffic_reports` + +Methods + +```python + + list_traffic_reports( + region_id: Optional[str] = None, + resource_path: Optional[str] = None, + since: Optional[datetime] = None, + until: Optional[datetime] = None, + count: int = 25, + depth: int = 1, + forbidden_uris: Optional[Sequence[str]] = None, + disable_geojson: bool = False, + ) -> Tuple[Sequence[Disruption], Sequence[TrafficReport], Pagination]: + Retrieves traffic reports for a specified region and resource path from the Navitia API. + +``` diff --git a/docs/api_support/vehicle_journeys.md b/docs/api_support/vehicle_journeys.md new file mode 100644 index 0000000..c6ba180 --- /dev/null +++ b/docs/api_support/vehicle_journeys.md @@ -0,0 +1,60 @@ +# Vehicle journeys + +API client for handling 'VehicleJourney' entities in the Navitia API. + +Official documentation: + +Property: `NavitiaClient.vehicle_journeys` + +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[VehicleJourney], Pagination]: + List vehicle journeys 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[VehicleJourney], Pagination]: + Get a vehicle journey 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[VehicleJourney], Pagination]: + List vehicle journeys 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[VehicleJourney], Pagination]: + Get a vehicle journey by its ID for given geographic coordinates. +``` diff --git a/docs/few_tips.md b/docs/few_tips.md new file mode 100644 index 0000000..8e71ed3 --- /dev/null +++ b/docs/few_tips.md @@ -0,0 +1,7 @@ +# Few tips on API usage + +## How to write a resource path ? + +A `resource_path` is the combination of a kind of resource and its id. + +For example, the `resource_path` of a line will be `line/line:foo`. diff --git a/navitia_client/client/apis/journeys_apis.py b/navitia_client/client/apis/journeys_apis.py index afe47e9..b6afa70 100644 --- a/navitia_client/client/apis/journeys_apis.py +++ b/navitia_client/client/apis/journeys_apis.py @@ -8,6 +8,8 @@ class JourneyApiClient(ApiBaseClient): """ A client class to interact with the Navitia API for fetching journey data. + See https://doc.navitia.io/#journeys + Methods ------- _get_journeys(url: str, filters: dict) -> Sequence[Journey]