ParkAPI Sources is a collection of converters from several different data sources to normalized ParkAPI data. ParkAPI does support parking for cars, for bikes and lockers. The data model is based on the original ParkAPI project and tries to stay compatible to DATEX II Parking Publication Light at any extension of the model.
We support following data sources:
name | purpose | type | uid | realtime |
---|---|---|---|---|
APCOA Services | car | pull | apcoa |
no |
Deutsche Bahn | car | pull | bahn_v2 |
no |
Stadt Bietigheim-Bissingen | car | pull | bietigheim_bissingen |
yes |
Barrierefreie Reisekette Baden-Württemberg: PKW-Parkplätze | car | pull | bfrk_bw_car |
no |
Barrierefreie Reisekette Baden-Württemberg: Fahrrad-Parkplätze | bike | pull | bfrk_bw_bike |
no |
Stadt Ellwangen | car | push (xlsx) | ellwangen |
no |
Stadt Buchen | car | push (json) | buchen |
yes |
Stadt Freiburg | car | pull | freiburg |
yes |
GOLDBECK Parking Services | car | push (xlsx) | goldbeck |
no |
Stadt Heidelberg | car | pull | heidelberg |
yes |
Stadt Herrenberg | car | pull | herrenberg |
no |
PARK SERVICE HÜFNER GmbH + Co. KG | car | push (xlsx) | huefner |
no |
Stadt Karlsruhe: PKW-Parkplätze | car | pull | karlsruhe |
yes |
Stadt Karlsruhe: Fahhrrad-Abstellangen | bike | pull | karlsruhe_bike |
no |
Kienzler: Bike and Ride | bike | pull | kienzler_bike_and_ride |
yes |
Kienzler: Karlsruhe | bike | pull | kienzler_karlruhe |
yes |
Kienzler: Neckarsulm | bike | pull | kienzler_neckarsulm |
yes |
Kienzler: Offenburg | bike | pull | kienzler_offenburg |
yes |
Kienzler: RadSafe | bike | pull | kienzler_rad_safe |
yes |
Kienzler: Stuttgart | bike | pull | kienzler_stuttgart |
yes |
Kienzler: VRN | bike | pull | kienzler_vrn |
yes |
Konstanz | car | pull | konstanz |
yes |
Stadt Konstanz: Fahrrad-Abstellanlagen | bike | push | konstanz_bike |
no |
Stadt Mannheim | car | push (json) | mannheim |
yes |
Stadt Neckarsulm: PKW-Parkplätze | car | pull | neckarsulm |
no |
Stadt Neckarsulm: Fahrrad-Abstellanlagen | bike | pull | neckarsulm_bike |
no |
Open-Data-Plattform öV Schweiz | car | pull (json) | opendata_swiss |
no |
P + M Baden-Württemberg | car | pull | p_m_bw |
yes |
Baden-Württemberg: Parken und Mitfahren | car | push (xlsx) | pum_bw |
no |
RadVIS Baden-Württemberg (experimental) | bike | pull | radvis_bw |
no |
Parkraumgesellschaft Baden-Württemberg | car | pull | pbw |
yes |
Stadt Pforzheim | car | push (csv) | pforzheim |
no |
Stadt Reutlingen: PKW-Parkplätze | car | push (csv) | reutlingen |
no |
Stadt Reutlingen: Fahrrad-Abstellanlagen | bike | push (csv) | reutlingen_bike |
no |
Stadt Stuttgart | car | push (json) | stuttgart |
yes |
Stadt Ulm | car | pull | ulm |
yes |
Verband Region Stuttgart: Bondorf | car | pull | vrs_bondorf |
yes |
Verband Region Stuttgart: Kirchheim | car | pull | vrs_kirchheim |
yes |
Verband Region Stuttgart: Neustadt | car | pull | vrs_neustadt |
yes |
Verband Region Stuttgart: Park and Ride | car | push (xlsx) | vrs_p_r |
no |
Verband Region Stuttgart: Vaihingen | car | pull | vrs_vaihingen |
yes |
New converters for new sources are always welcome, please have a look at "Contribute" below.
ParkAPI Sources is a python module published at PyPI. Therefore, you can install it by
pip install parkapi-sources
If you use parkapi-sources in a project, we recommend to fix the version. As long as parkapi-sources is beta, breaking changes might be introduced on minor version level (like: change from 0.1.1 to 0.2.0). As soon as 1.0 is released, we will follow Semantic Versioning, which means that breaking changes will just appear on major version changes (like: change from 1.1.2 to 2.0.0). You can expect a lot of changes in the minor version level, as any new converter is a new feature.
Your starting point is always the ParkAPISources
where all Sources are registered.
from parkapi_sources import ParkAPISources
my_sources = ParkAPISources()
ParkAPISources
accepts following parameters:
config: Optional[dict] = None
is a dictionary for config values, especially secrets.converter_uids: Optional[list[str]] = None
is used for loading just the converter uids you want to loadno_pull_converter: bool = False
is used for limiting converters to pull convertersno_push_converter: bool = False
is used for limiting converters to push converters
Config values are mostly individual for specific converters: if there are required config values, they are defined at the converter definition right at the top:
required_config_keys = ['MY_SECRET']
ParkAPISources
offers a method to check if all config values are set:
from parkapi_sources import ParkAPISources
my_sources = ParkAPISources()
my_sources.check_credentials()
If not all config values are set, a MissingConfigException
is thrown. It's recommended to run this check after initializing the module
to prevent exceptions during runtime.
Besides converter-individual config values, there are two global values which can be used to configure the source of GeoJSON files. Per default, static GeoJSON files are fetched from this repository. This behaviour can be changed:
STATIC_GEOJSON_BASE_URL
defines another base URL for GeoJSON filesSTATIC_GEOJSON_BASE_PATH
defines a lokal path instead, so the application will load files locally without network requests
After initializing, you will find all initialized converters at ParkAPISources.converter_by_uid
. As the input is very different, so are
the methods you have to use. In general, you can differ between two major strategies:
Pull converters are responsible for getting data from an external data source. This can be an REST endpoints as well as HTML which is scraped. Pull converters always split up in static and realtime data, because at most sources, this is not the same. Each pull converter has two methods:
get_static_parking_sites(self) -> tuple[list[StaticParkingSiteInput], list[ImportParkingSiteException]]:
def get_realtime_parking_sites(self) -> tuple[list[RealtimeParkingSiteInput], list[ImportParkingSiteException]]:
Push converters are responsible to handle data which is pushed to the service using defined endpoints. Usually, these converters are used as a handler behind HTTP endpoints, but of course you can use them in other ways, too, for example command line scripts.
Push converters always handle specific formats, therefore, there are multiple types of push converters. All push converters return a
tuple[list[StaticParkingSiteInput | RealtimeParkingSiteInput], list[ImportParkingSiteException]]
, therefore they decided based on the
given data if it's static or realtime data they got - or even both, then each dataset ends up in two entries in the first list.
- A
CsvConverter
handles CSV files:handle_csv_string(self, data: StringIO)
- A
JsonConverter
handles JSON based data:handle_json(self, data: dict | list)
- A
XlsxConverter
handles XMLX data:def handle_xlsx(self, workbook: Workbook)
parsed byopenpyxl
- A
XmlConverter
handles XML data:def handle_xml(self, root: Element)
parsed bylxml
At webapp/models/parking_site_inputs.py
, you can find the definition of StaticParkingSiteInput
and RealtimeParkingSiteInput
. These
dataclasses
are also validataclasses
, so you can be sure that the data you get is validated.
We are happy about any contributions. We do not expect that yoy can develop Python, but of course things might speed up if
As ParkAPI-Sources integrates a lot of external data sources, sometimes without a proper definition, converters might run into issues because of changes on the data source side. If you see that happening, please add a bug report at the issues. If possible, please add the data which fails.
If you see a nice data source which is not covered by ParkAPI-sources, you can always create a feature request at our issues. If you do so, please add the data you found, so we can actually build the converter. If possible, please try to find out a licence, too.
We always welcome merge requests with new converters. A merge request should contain the following:
- MIT licenced code
- A converter which validates the input in a way that the output follows the data model
- A test with example data to ensure that the converter works with current data
First you have to determine which type of converter you need. If you get the data from an endpoint, you will need a PushConverter
, if
you have a file you want to push via HTTP or CLI, you need a PullConverter
.
In order to write a converter, you need a directory at converters
. Please name your directory in a way that it points to the actual
converter you will write. If it's just one converter, the uid
is usually the best approach.
At converters/your-converter
, you will at least need a converter.py
and an __init__.py
. In most cases, you will also need some
validataclasses
you can put in models.py
. Validation is crucial in this library, because the users of this library should not think
invalid data. Additionally, if you have very specific new data types, you can write new validataclass
validators you can usually put in
validators.py
.
In order to proof that the validator works, we need to test the basic functionality. In order to do this, we need a snapshot of the data
which should be integrated. Common place for this data is tests/converters/data/filename-starting-with-uid.ending
. This data should be
used in one or multiple tests (in several cases two tests, one for static, one for realtime data) stored at tests/converters/uid_test.py
.
If you test a PullConverter
, you will need no mock requests. This can be done using the fantastic
requests_mock
library.
If you created new validators, these should be tested with different inputs. Usually, pytest.parametrize
is a nice approach to do this.
If you want to migrate a v1 or v2 converter, you can re-use some of the code. There is a paradigm change, though: parkapi-source-v3
enforces a strict validation after transforming the data, while v1 and v2 converters don't. ParkAPI v1 / v2 converters are always pull
converters, so the base class is always PullConverter
.
Instead of defining POOL
, you will set source_info
at the same place. Attributes are almost the same, except for id
was renamed to
uid
, and there is the new attribute has_realtime_data
, which has to be set.
ParkAPI v1 and v2 used two methods for static and realtime data, just as parkapi-sources-v3
:
- the old static data handling
def get_lot_infos(self) -> List[LotInfo]:
isget_static_parking_sites(self) -> tuple[list[StaticParkingSiteInput], list[ImportParkingSiteException]]:
inparkapi-sources-v3
. - the old realtime data handling
def get_lot_data(self) -> List[LotData]:
isdef get_realtime_parking_sites(self) -> tuple[list[RealtimeParkingSiteInput], list[ImportParkingSiteException]]:
inparkapi-sources-v3
.
The result objects have quite the same idea, too:
LotInfo
getsStaticParkingSiteInput
LotData
getsRealtimeParkingSiteInput
There's also a helper for scraped content: before, there was self.request_soup(self.POOL.public_url)
in order to get a BeautifulSoup
element. Now, there is a helper mixin called PullScraperMixin
. You can use it this way:
class MyPullConverter(PullConverter, PullScraperMixin):
Additionally, there is another mixin for the GeoJSON files you already know from v1 and v2 converters: StaticGeojsonDataMixin
. Using this,
you can just define the static data method this way:
def get_static_parking_sites(self) -> tuple[list[StaticParkingSiteInput], list[ImportParkingSiteException]]:
return self._get_static_parking_site_inputs_and_exceptions(source_uid=self.source_info.uid)
The default location for GeoJSON files is a separate repository.
Please keep in mind that you will have to add tests for the migrated scraper.
As we try to keep a consistent code style, please lint your code before creating the merge request. We use ruff
for linting and
formatting. There is Makefile target to do both: make lint
. It runs the following commands:
ruff format ./src ./tests
ruff check --fix ./src ./tests
If you don't have ruff
installed globally, you can create a virtual environment for these tools:
virtualenv venv
source venv/bin/activate
pip install -r requirements.txt -r requirements-dev.txt
ruff format ./src ./tests
ruff check --fix ./src ./tests
All available converters should be registered at the ParkAPISources
class in order to make them accessible for users of this library, so
please register your converter there. The new converter should also be added to the table in this README.md file.
If you created a merge request, the maintainers will review your code. If everything is fine, it will be merged to main
, and a new
release will be created soon. As written above, we follow SemVer, so any new converter will add plus one to the minor version. In order to
use this new release, please keep in mind to update your requirements.txt
/ update the dependency manager you use.
This library is under MIT licence. Please look at LICENCE.txt
for details.