├── .gitignore ├── LICENSE ├── README.md ├── azure-pipelines.yml ├── de ├── docs │ ├── api.md │ ├── assets │ │ ├── css │ │ │ └── custom.css │ │ ├── fonts │ │ │ ├── roboto-mono-v12-latin-regular.woff │ │ │ ├── roboto-mono-v12-latin-regular.woff2 │ │ │ ├── roboto-v20-latin-300.woff │ │ │ ├── roboto-v20-latin-300.woff2 │ │ │ ├── roboto-v20-latin-700.woff │ │ │ ├── roboto-v20-latin-700.woff2 │ │ │ ├── roboto-v20-latin-italic.woff │ │ │ ├── roboto-v20-latin-italic.woff2 │ │ │ ├── roboto-v20-latin-regular.woff │ │ │ └── roboto-v20-latin-regular.woff2 │ │ └── logos │ │ │ ├── favicon.ico │ │ │ └── logo.svg │ ├── austria.md │ ├── change-log-data.md │ ├── change-log-webservice.md │ ├── community.md │ ├── errors.md │ ├── faq.md │ ├── fulltextsearch.md │ ├── germany.md │ ├── index.md │ ├── libraries.md │ ├── liechtenstein.md │ ├── paging.md │ ├── regex.md │ ├── sources.md │ ├── switzerland.md │ └── url-encoding.md └── mkdocs.yml ├── en ├── docs │ ├── api.md │ ├── assets │ │ ├── css │ │ │ └── custom.css │ │ ├── fonts │ │ │ ├── roboto-mono-v12-latin-regular.woff │ │ │ ├── roboto-mono-v12-latin-regular.woff2 │ │ │ ├── roboto-v20-latin-300.woff │ │ │ ├── roboto-v20-latin-300.woff2 │ │ │ ├── roboto-v20-latin-700.woff │ │ │ ├── roboto-v20-latin-700.woff2 │ │ │ ├── roboto-v20-latin-italic.woff │ │ │ ├── roboto-v20-latin-italic.woff2 │ │ │ ├── roboto-v20-latin-regular.woff │ │ │ └── roboto-v20-latin-regular.woff2 │ │ └── logos │ │ │ ├── favicon.ico │ │ │ └── logo.svg │ ├── austria.md │ ├── change-log-data.md │ ├── change-log-webservice.md │ ├── community.md │ ├── errors.md │ ├── faq.md │ ├── fulltextsearch.md │ ├── germany.md │ ├── index.md │ ├── libraries.md │ ├── liechtenstein.md │ ├── paging.md │ ├── regex.md │ ├── sources.md │ ├── switzerland.md │ └── url-encoding.md └── mkdocs.yml └── nginx-maintenance.html /.gitignore: -------------------------------------------------------------------------------- 1 | de/site/ 2 | en/site/ 3 | -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | Attribution-NonCommercial 4.0 International 2 | 3 | ======================================================================= 4 | 5 | Creative Commons Corporation ("Creative Commons") is not a law firm and 6 | does not provide legal services or legal advice. Distribution of 7 | Creative Commons public licenses does not create a lawyer-client or 8 | other relationship. Creative Commons makes its licenses and related 9 | information available on an "as-is" basis. Creative Commons gives no 10 | warranties regarding its licenses, any material licensed under their 11 | terms and conditions, or any related information. Creative Commons 12 | disclaims all liability for damages resulting from their use to the 13 | fullest extent possible. 14 | 15 | Using Creative Commons Public Licenses 16 | 17 | Creative Commons public licenses provide a standard set of terms and 18 | conditions that creators and other rights holders may use to share 19 | original works of authorship and other material subject to copyright 20 | and certain other rights specified in the public license below. The 21 | following considerations are for informational purposes only, are not 22 | exhaustive, and do not form part of our licenses. 23 | 24 | Considerations for licensors: Our public licenses are 25 | intended for use by those authorized to give the public 26 | permission to use material in ways otherwise restricted by 27 | copyright and certain other rights. Our licenses are 28 | irrevocable. Licensors should read and understand the terms 29 | and conditions of the license they choose before applying it. 30 | Licensors should also secure all rights necessary before 31 | applying our licenses so that the public can reuse the 32 | material as expected. Licensors should clearly mark any 33 | material not subject to the license. This includes other CC- 34 | licensed material, or material used under an exception or 35 | limitation to copyright. More considerations for licensors: 36 | wiki.creativecommons.org/Considerations_for_licensors 37 | 38 | Considerations for the public: By using one of our public 39 | licenses, a licensor grants the public permission to use the 40 | licensed material under specified terms and conditions. If 41 | the licensor's permission is not necessary for any reason--for 42 | example, because of any applicable exception or limitation to 43 | copyright--then that use is not regulated by the license. Our 44 | licenses grant only permissions under copyright and certain 45 | other rights that a licensor has authority to grant. Use of 46 | the licensed material may still be restricted for other 47 | reasons, including because others have copyright or other 48 | rights in the material. A licensor may make special requests, 49 | such as asking that all changes be marked or described. 50 | Although not required by our licenses, you are encouraged to 51 | respect those requests where reasonable. More considerations 52 | for the public: 53 | wiki.creativecommons.org/Considerations_for_licensees 54 | 55 | ======================================================================= 56 | 57 | Creative Commons Attribution-NonCommercial 4.0 International Public 58 | License 59 | 60 | By exercising the Licensed Rights (defined below), You accept and agree 61 | to be bound by the terms and conditions of this Creative Commons 62 | Attribution-NonCommercial 4.0 International Public License ("Public 63 | License"). To the extent this Public License may be interpreted as a 64 | contract, You are granted the Licensed Rights in consideration of Your 65 | acceptance of these terms and conditions, and the Licensor grants You 66 | such rights in consideration of benefits the Licensor receives from 67 | making the Licensed Material available under these terms and 68 | conditions. 69 | 70 | 71 | Section 1 -- Definitions. 72 | 73 | a. Adapted Material means material subject to Copyright and Similar 74 | Rights that is derived from or based upon the Licensed Material 75 | and in which the Licensed Material is translated, altered, 76 | arranged, transformed, or otherwise modified in a manner requiring 77 | permission under the Copyright and Similar Rights held by the 78 | Licensor. For purposes of this Public License, where the Licensed 79 | Material is a musical work, performance, or sound recording, 80 | Adapted Material is always produced where the Licensed Material is 81 | synched in timed relation with a moving image. 82 | 83 | b. Adapter's License means the license You apply to Your Copyright 84 | and Similar Rights in Your contributions to Adapted Material in 85 | accordance with the terms and conditions of this Public License. 86 | 87 | c. Copyright and Similar Rights means copyright and/or similar rights 88 | closely related to copyright including, without limitation, 89 | performance, broadcast, sound recording, and Sui Generis Database 90 | Rights, without regard to how the rights are labeled or 91 | categorized. For purposes of this Public License, the rights 92 | specified in Section 2(b)(1)-(2) are not Copyright and Similar 93 | Rights. 94 | d. Effective Technological Measures means those measures that, in the 95 | absence of proper authority, may not be circumvented under laws 96 | fulfilling obligations under Article 11 of the WIPO Copyright 97 | Treaty adopted on December 20, 1996, and/or similar international 98 | agreements. 99 | 100 | e. Exceptions and Limitations means fair use, fair dealing, and/or 101 | any other exception or limitation to Copyright and Similar Rights 102 | that applies to Your use of the Licensed Material. 103 | 104 | f. Licensed Material means the artistic or literary work, database, 105 | or other material to which the Licensor applied this Public 106 | License. 107 | 108 | g. Licensed Rights means the rights granted to You subject to the 109 | terms and conditions of this Public License, which are limited to 110 | all Copyright and Similar Rights that apply to Your use of the 111 | Licensed Material and that the Licensor has authority to license. 112 | 113 | h. Licensor means the individual(s) or entity(ies) granting rights 114 | under this Public License. 115 | 116 | i. NonCommercial means not primarily intended for or directed towards 117 | commercial advantage or monetary compensation. For purposes of 118 | this Public License, the exchange of the Licensed Material for 119 | other material subject to Copyright and Similar Rights by digital 120 | file-sharing or similar means is NonCommercial provided there is 121 | no payment of monetary compensation in connection with the 122 | exchange. 123 | 124 | j. Share means to provide material to the public by any means or 125 | process that requires permission under the Licensed Rights, such 126 | as reproduction, public display, public performance, distribution, 127 | dissemination, communication, or importation, and to make material 128 | available to the public including in ways that members of the 129 | public may access the material from a place and at a time 130 | individually chosen by them. 131 | 132 | k. Sui Generis Database Rights means rights other than copyright 133 | resulting from Directive 96/9/EC of the European Parliament and of 134 | the Council of 11 March 1996 on the legal protection of databases, 135 | as amended and/or succeeded, as well as other essentially 136 | equivalent rights anywhere in the world. 137 | 138 | l. You means the individual or entity exercising the Licensed Rights 139 | under this Public License. Your has a corresponding meaning. 140 | 141 | 142 | Section 2 -- Scope. 143 | 144 | a. License grant. 145 | 146 | 1. Subject to the terms and conditions of this Public License, 147 | the Licensor hereby grants You a worldwide, royalty-free, 148 | non-sublicensable, non-exclusive, irrevocable license to 149 | exercise the Licensed Rights in the Licensed Material to: 150 | 151 | a. reproduce and Share the Licensed Material, in whole or 152 | in part, for NonCommercial purposes only; and 153 | 154 | b. produce, reproduce, and Share Adapted Material for 155 | NonCommercial purposes only. 156 | 157 | 2. Exceptions and Limitations. For the avoidance of doubt, where 158 | Exceptions and Limitations apply to Your use, this Public 159 | License does not apply, and You do not need to comply with 160 | its terms and conditions. 161 | 162 | 3. Term. The term of this Public License is specified in Section 163 | 6(a). 164 | 165 | 4. Media and formats; technical modifications allowed. The 166 | Licensor authorizes You to exercise the Licensed Rights in 167 | all media and formats whether now known or hereafter created, 168 | and to make technical modifications necessary to do so. The 169 | Licensor waives and/or agrees not to assert any right or 170 | authority to forbid You from making technical modifications 171 | necessary to exercise the Licensed Rights, including 172 | technical modifications necessary to circumvent Effective 173 | Technological Measures. For purposes of this Public License, 174 | simply making modifications authorized by this Section 2(a) 175 | (4) never produces Adapted Material. 176 | 177 | 5. Downstream recipients. 178 | 179 | a. Offer from the Licensor -- Licensed Material. Every 180 | recipient of the Licensed Material automatically 181 | receives an offer from the Licensor to exercise the 182 | Licensed Rights under the terms and conditions of this 183 | Public License. 184 | 185 | b. No downstream restrictions. You may not offer or impose 186 | any additional or different terms or conditions on, or 187 | apply any Effective Technological Measures to, the 188 | Licensed Material if doing so restricts exercise of the 189 | Licensed Rights by any recipient of the Licensed 190 | Material. 191 | 192 | 6. No endorsement. Nothing in this Public License constitutes or 193 | may be construed as permission to assert or imply that You 194 | are, or that Your use of the Licensed Material is, connected 195 | with, or sponsored, endorsed, or granted official status by, 196 | the Licensor or others designated to receive attribution as 197 | provided in Section 3(a)(1)(A)(i). 198 | 199 | b. Other rights. 200 | 201 | 1. Moral rights, such as the right of integrity, are not 202 | licensed under this Public License, nor are publicity, 203 | privacy, and/or other similar personality rights; however, to 204 | the extent possible, the Licensor waives and/or agrees not to 205 | assert any such rights held by the Licensor to the limited 206 | extent necessary to allow You to exercise the Licensed 207 | Rights, but not otherwise. 208 | 209 | 2. Patent and trademark rights are not licensed under this 210 | Public License. 211 | 212 | 3. To the extent possible, the Licensor waives any right to 213 | collect royalties from You for the exercise of the Licensed 214 | Rights, whether directly or through a collecting society 215 | under any voluntary or waivable statutory or compulsory 216 | licensing scheme. In all other cases the Licensor expressly 217 | reserves any right to collect such royalties, including when 218 | the Licensed Material is used other than for NonCommercial 219 | purposes. 220 | 221 | 222 | Section 3 -- License Conditions. 223 | 224 | Your exercise of the Licensed Rights is expressly made subject to the 225 | following conditions. 226 | 227 | a. Attribution. 228 | 229 | 1. If You Share the Licensed Material (including in modified 230 | form), You must: 231 | 232 | a. retain the following if it is supplied by the Licensor 233 | with the Licensed Material: 234 | 235 | i. identification of the creator(s) of the Licensed 236 | Material and any others designated to receive 237 | attribution, in any reasonable manner requested by 238 | the Licensor (including by pseudonym if 239 | designated); 240 | 241 | ii. a copyright notice; 242 | 243 | iii. a notice that refers to this Public License; 244 | 245 | iv. a notice that refers to the disclaimer of 246 | warranties; 247 | 248 | v. a URI or hyperlink to the Licensed Material to the 249 | extent reasonably practicable; 250 | 251 | b. indicate if You modified the Licensed Material and 252 | retain an indication of any previous modifications; and 253 | 254 | c. indicate the Licensed Material is licensed under this 255 | Public License, and include the text of, or the URI or 256 | hyperlink to, this Public License. 257 | 258 | 2. You may satisfy the conditions in Section 3(a)(1) in any 259 | reasonable manner based on the medium, means, and context in 260 | which You Share the Licensed Material. For example, it may be 261 | reasonable to satisfy the conditions by providing a URI or 262 | hyperlink to a resource that includes the required 263 | information. 264 | 265 | 3. If requested by the Licensor, You must remove any of the 266 | information required by Section 3(a)(1)(A) to the extent 267 | reasonably practicable. 268 | 269 | 4. If You Share Adapted Material You produce, the Adapter's 270 | License You apply must not prevent recipients of the Adapted 271 | Material from complying with this Public License. 272 | 273 | 274 | Section 4 -- Sui Generis Database Rights. 275 | 276 | Where the Licensed Rights include Sui Generis Database Rights that 277 | apply to Your use of the Licensed Material: 278 | 279 | a. for the avoidance of doubt, Section 2(a)(1) grants You the right 280 | to extract, reuse, reproduce, and Share all or a substantial 281 | portion of the contents of the database for NonCommercial purposes 282 | only; 283 | 284 | b. if You include all or a substantial portion of the database 285 | contents in a database in which You have Sui Generis Database 286 | Rights, then the database in which You have Sui Generis Database 287 | Rights (but not its individual contents) is Adapted Material; and 288 | 289 | c. You must comply with the conditions in Section 3(a) if You Share 290 | all or a substantial portion of the contents of the database. 291 | 292 | For the avoidance of doubt, this Section 4 supplements and does not 293 | replace Your obligations under this Public License where the Licensed 294 | Rights include other Copyright and Similar Rights. 295 | 296 | 297 | Section 5 -- Disclaimer of Warranties and Limitation of Liability. 298 | 299 | a. UNLESS OTHERWISE SEPARATELY UNDERTAKEN BY THE LICENSOR, TO THE 300 | EXTENT POSSIBLE, THE LICENSOR OFFERS THE LICENSED MATERIAL AS-IS 301 | AND AS-AVAILABLE, AND MAKES NO REPRESENTATIONS OR WARRANTIES OF 302 | ANY KIND CONCERNING THE LICENSED MATERIAL, WHETHER EXPRESS, 303 | IMPLIED, STATUTORY, OR OTHER. THIS INCLUDES, WITHOUT LIMITATION, 304 | WARRANTIES OF TITLE, MERCHANTABILITY, FITNESS FOR A PARTICULAR 305 | PURPOSE, NON-INFRINGEMENT, ABSENCE OF LATENT OR OTHER DEFECTS, 306 | ACCURACY, OR THE PRESENCE OR ABSENCE OF ERRORS, WHETHER OR NOT 307 | KNOWN OR DISCOVERABLE. WHERE DISCLAIMERS OF WARRANTIES ARE NOT 308 | ALLOWED IN FULL OR IN PART, THIS DISCLAIMER MAY NOT APPLY TO YOU. 309 | 310 | b. TO THE EXTENT POSSIBLE, IN NO EVENT WILL THE LICENSOR BE LIABLE 311 | TO YOU ON ANY LEGAL THEORY (INCLUDING, WITHOUT LIMITATION, 312 | NEGLIGENCE) OR OTHERWISE FOR ANY DIRECT, SPECIAL, INDIRECT, 313 | INCIDENTAL, CONSEQUENTIAL, PUNITIVE, EXEMPLARY, OR OTHER LOSSES, 314 | COSTS, EXPENSES, OR DAMAGES ARISING OUT OF THIS PUBLIC LICENSE OR 315 | USE OF THE LICENSED MATERIAL, EVEN IF THE LICENSOR HAS BEEN 316 | ADVISED OF THE POSSIBILITY OF SUCH LOSSES, COSTS, EXPENSES, OR 317 | DAMAGES. WHERE A LIMITATION OF LIABILITY IS NOT ALLOWED IN FULL OR 318 | IN PART, THIS LIMITATION MAY NOT APPLY TO YOU. 319 | 320 | c. The disclaimer of warranties and limitation of liability provided 321 | above shall be interpreted in a manner that, to the extent 322 | possible, most closely approximates an absolute disclaimer and 323 | waiver of all liability. 324 | 325 | 326 | Section 6 -- Term and Termination. 327 | 328 | a. This Public License applies for the term of the Copyright and 329 | Similar Rights licensed here. However, if You fail to comply with 330 | this Public License, then Your rights under this Public License 331 | terminate automatically. 332 | 333 | b. Where Your right to use the Licensed Material has terminated under 334 | Section 6(a), it reinstates: 335 | 336 | 1. automatically as of the date the violation is cured, provided 337 | it is cured within 30 days of Your discovery of the 338 | violation; or 339 | 340 | 2. upon express reinstatement by the Licensor. 341 | 342 | For the avoidance of doubt, this Section 6(b) does not affect any 343 | right the Licensor may have to seek remedies for Your violations 344 | of this Public License. 345 | 346 | c. For the avoidance of doubt, the Licensor may also offer the 347 | Licensed Material under separate terms or conditions or stop 348 | distributing the Licensed Material at any time; however, doing so 349 | will not terminate this Public License. 350 | 351 | d. Sections 1, 5, 6, 7, and 8 survive termination of this Public 352 | License. 353 | 354 | 355 | Section 7 -- Other Terms and Conditions. 356 | 357 | a. The Licensor shall not be bound by any additional or different 358 | terms or conditions communicated by You unless expressly agreed. 359 | 360 | b. Any arrangements, understandings, or agreements regarding the 361 | Licensed Material not stated herein are separate from and 362 | independent of the terms and conditions of this Public License. 363 | 364 | 365 | Section 8 -- Interpretation. 366 | 367 | a. For the avoidance of doubt, this Public License does not, and 368 | shall not be interpreted to, reduce, limit, restrict, or impose 369 | conditions on any use of the Licensed Material that could lawfully 370 | be made without permission under this Public License. 371 | 372 | b. To the extent possible, if any provision of this Public License is 373 | deemed unenforceable, it shall be automatically reformed to the 374 | minimum extent necessary to make it enforceable. If the provision 375 | cannot be reformed, it shall be severed from this Public License 376 | without affecting the enforceability of the remaining terms and 377 | conditions. 378 | 379 | c. No term or condition of this Public License will be waived and no 380 | failure to comply consented to unless expressly agreed to by the 381 | Licensor. 382 | 383 | d. Nothing in this Public License constitutes or may be interpreted 384 | as a limitation upon, or waiver of, any privileges and immunities 385 | that apply to the Licensor or You, including from the legal 386 | processes of any jurisdiction or authority. 387 | 388 | ======================================================================= 389 | 390 | Creative Commons is not a party to its public 391 | licenses. Notwithstanding, Creative Commons may elect to apply one of 392 | its public licenses to material it publishes and in those instances 393 | will be considered the “Licensor.” The text of the Creative Commons 394 | public licenses is dedicated to the public domain under the CC0 Public 395 | Domain Dedication. Except for the limited purpose of indicating that 396 | material is shared under a Creative Commons public license or as 397 | otherwise permitted by the Creative Commons policies published at 398 | creativecommons.org/policies, Creative Commons does not authorize the 399 | use of the trademark "Creative Commons" or any other trademark or logo 400 | of Creative Commons without its prior written consent including, 401 | without limitation, in connection with any unauthorized modifications 402 | to any of its public licenses or any other arrangements, 403 | understandings, or agreements concerning use of licensed material. For 404 | the avoidance of doubt, this paragraph does not form part of the 405 | public licenses. 406 | 407 | Creative Commons may be contacted at creativecommons.org. 408 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # OpenPLZ API Documentation 2 | 3 | This is the documentation for the OpenPLZ API project. The documentation is Open Source and we have implemented it using [MkDocs](https://www.mkdocs.org) and [Material for MkDocs](https://squidfunk.github.io/mkdocs-material). 4 | 5 | ## Install MkDocs for Windows 6 | 7 | 1. Install [Python](https://www.python.org). Go to the [Python downloads](https://www.python.org/downloads/) page and download the latest version for Windows. 8 | 9 | 2. Launch the installer and follow the on-screen instructions. 10 | 11 | 3. Run the command prompt as Administrator. 12 | 13 | 4. Enter the command `python --version` and `pip --version` to check the Python installation. In both cases a version number should appear as an output in the command prompt. 14 | 15 | 5. Enter the command `pip install mkdocs mkdocs-material mkdocs-minify-plugin` to install the *MkDocs* Python package, the *Material for MkDocs* theme and the MkDocs plugin [Minify](https://github.com/byrnereese/mkdocs-minify-plugin). 16 | 17 | 6. Final test: Enter the command `mkdocs --version`. A version nummer in the command prompt will let you know if everything has been installed correctly. 18 | 19 | ## Clone Repository 20 | 21 | This repository is a Git repository. To clone the repository to a local commputer you will need a Git client. Either install [Git for Windows](https://gitforwindows.org/) and use the command prompt or install one of the many GUIs. We recommend [GitHub Desktop](https://desktop.github.com) or [SourceTree](https://www.sourcetreeapp.com). 22 | 23 | 1. Create a local directory for the documentation e.g. `c:\openplzapi`. 24 | 25 | 2. Open the command prompt and change to directory `c:\openplzapi`. 26 | 27 | 3. Enter the command `git clone https://github.com/openpotato/openplzapi.website.git` to clone the repository. 28 | 29 | ## Download Repository as Zip Archive 30 | 31 | If you don't want to use Git you can even download the repository as a Zip Archive: 32 | 33 | 1. Open the URL `https://github.com/openpotato/openplzapi.website` in your web browser 34 | 35 | 2. Click on the `Clone or download` button then select `Download ZIP`. 36 | 37 | 3. Extract the Zip Archive to a local folder, e.g. `c:\openplzapi`. 38 | 39 | ## Using MkDocs 40 | 41 | You have installed Python and MkDocs, cloned the repository or downloaded it as a Zip Archive. Now you can generate the documentation locally on your computer. 42 | 43 | 1. Start the command prompt and change to the directory `c:\openplzapi\de` for German documentation or `c:\openplzapi\en` for the English documentation. 44 | 45 | 2. Enter the command `mkdocs build`. The documentation will be regenerated. 46 | 47 | 3. To display the result, enter the command `mkdocs serve` and open the URL `http://127.0.0.1:8000` in your Web browser. 48 | 49 | The table of contents can be found in the `mkdocs.yml` file and the individual chapters are in the `docs` subdirectory. 50 | 51 | ## Can I help? 52 | 53 | Yes, that would be much appreciated. The best way to help is to post a response via the Issue Tracker and/or submit corrections via a Pull Request. -------------------------------------------------------------------------------- /azure-pipelines.yml: -------------------------------------------------------------------------------- 1 | pool: 2 | vmImage: 'windows-2022' 3 | 4 | variables: 5 | - group: 'github-config' 6 | 7 | steps: 8 | - task: UsePythonVersion@0 9 | inputs: 10 | versionSpec: '3.x' 11 | addToPath: true 12 | architecture: 'x64' 13 | - task: PowerShell@2 14 | displayName: Install MkDocs 15 | inputs: 16 | targetType: 'inline' 17 | script: | 18 | pip install mkdocs mkdocs-material mkdocs-minify-plugin --disable-pip-version-check 19 | failOnStderr: false 20 | workingDirectory: '$(Build.SourcesDirectory)' 21 | - task: PowerShell@2 22 | displayName: Build MkDocs project for DE 23 | inputs: 24 | targetType: 'inline' 25 | script: | 26 | mkdocs build -q 27 | failOnStderr: true 28 | workingDirectory: '$(Build.SourcesDirectory)/de' 29 | - task: PowerShell@2 30 | displayName: Build MkDocs project for EN 31 | inputs: 32 | targetType: 'inline' 33 | script: | 34 | mkdocs build -q 35 | failOnStderr: true 36 | workingDirectory: '$(Build.SourcesDirectory)/en' 37 | - task: ArchiveFiles@2 38 | displayName: 'Create Zip archive for DE' 39 | inputs: 40 | rootFolderOrFile: 'de/site' 41 | includeRootFolder: false 42 | archiveType: 'zip' 43 | archiveFile: '$(Build.ArtifactStagingDirectory)/$(Build.BuildId).de.zip' 44 | replaceExistingArchive: true 45 | - task: ArchiveFiles@2 46 | displayName: 'Create Zip archive for EN' 47 | inputs: 48 | rootFolderOrFile: 'en/site' 49 | includeRootFolder: false 50 | archiveType: 'zip' 51 | archiveFile: '$(Build.ArtifactStagingDirectory)/$(Build.BuildId).en.zip' 52 | replaceExistingArchive: true 53 | - task: CopyFiles@2 54 | displayName: 'Copy Maintenance Page' 55 | inputs: 56 | Contents: 'nginx-maintenance.html' 57 | TargetFolder: '$(Build.ArtifactStagingDirectory)' 58 | OverWrite: true 59 | - task: PublishBuildArtifacts@1 60 | displayName: 'Publish build artifacts' 61 | inputs: 62 | PathtoPublish: '$(Build.ArtifactStagingDirectory)' 63 | ArtifactName: 'drop' 64 | publishLocation: 'Container' 65 | - task: PowerShell@2 66 | displayName: 'Push to GitHub' 67 | condition: and(succeeded(), eq(variables['Build.SourceBranch'], 'refs/heads/main')) 68 | inputs: 69 | targetType: 'inline' 70 | script: | 71 | git remote add github https://$(PAT)@github.com/openpotato/openplzapi.website.git 72 | git fetch github 73 | git checkout . 74 | git push github HEAD:main 75 | git push --tags github HEAD:main 76 | pwsh: true 77 | -------------------------------------------------------------------------------- /de/docs/api.md: -------------------------------------------------------------------------------- 1 | Die komplette **OpenPLZ API** liegt als OpenAPI-Definition vor und kann mittels einer automatisch generierten Oberfläche interaktiv gestestet werden. 2 | 3 | [OpenPLZ API testen](https://openplzapi.org/swagger){ .md-button .md-button--primary } 4 | 5 | !!! note "OpenAPI" 6 | 7 | Die [OpenAPI-Spezifikation](https://spec.openapis.org/oas/latest.html) definiert eine standardisierte, programmiersprachenunabhängige Schnittstellenbeschreibung für HTTP-basierte APIs. Die Spezifikation wird von der [OpenAPI Initiative](https://www.openapis.org/about) überwacht und weiterentwickelt. 8 | 9 | Das Monitoring der OpenPLZ API Dienste ist ebenfalls Open Source. 10 | 11 | [OpenPLZ API Live Status](https://openpotato.github.io/uptime/){ .md-button .md-button--primary } 12 | -------------------------------------------------------------------------------- /de/docs/assets/css/custom.css: -------------------------------------------------------------------------------- 1 | /* roboto-300 - latin */ 2 | @font-face { 3 | font-family: 'Roboto'; 4 | font-style: normal; 5 | font-weight: 300; 6 | src: local('Roboto Light'), local('Roboto-Light'), 7 | url('../fonts/roboto-v20-latin-300.woff2') format('woff2'), /* Chrome 26+, Opera 23+, Firefox 39+ */ 8 | url('../fonts/roboto-v20-latin-300.woff') format('woff'); /* Chrome 6+, Firefox 3.6+, IE 9+, Safari 5.1+ */ 9 | } 10 | /* roboto-regular - latin */ 11 | @font-face { 12 | font-family: 'Roboto'; 13 | font-style: normal; 14 | font-weight: 400; 15 | src: local('Roboto'), local('Roboto-Regular'), 16 | url('../fonts/roboto-v20-latin-regular.woff2') format('woff2'), /* Chrome 26+, Opera 23+, Firefox 39+ */ 17 | url('../fonts/roboto-v20-latin-regular.woff') format('woff'); /* Chrome 6+, Firefox 3.6+, IE 9+, Safari 5.1+ */ 18 | } 19 | /* roboto-italic - latin */ 20 | @font-face { 21 | font-family: 'Roboto'; 22 | font-style: italic; 23 | font-weight: 400; 24 | src: local('Roboto Italic'), local('Roboto-Italic'), 25 | url('../fonts/roboto-v20-latin-italic.woff2') format('woff2'), /* Chrome 26+, Opera 23+, Firefox 39+ */ 26 | url('../fonts/roboto-v20-latin-italic.woff') format('woff'); /* Chrome 6+, Firefox 3.6+, IE 9+, Safari 5.1+ */ 27 | } 28 | /* roboto-700 - latin */ 29 | @font-face { 30 | font-family: 'Roboto'; 31 | font-style: normal; 32 | font-weight: 700; 33 | src: local('Roboto Bold'), local('Roboto-Bold'), 34 | url('../fonts/roboto-v20-latin-700.woff2') format('woff2'), /* Chrome 26+, Opera 23+, Firefox 39+ */ 35 | url('../fonts/roboto-v20-latin-700.woff') format('woff'); /* Chrome 6+, Firefox 3.6+, IE 9+, Safari 5.1+ */ 36 | } 37 | /* roboto-mono-regular - latin */ 38 | @font-face { 39 | font-family: 'Roboto Mono'; 40 | font-style: normal; 41 | font-weight: 400; 42 | src: local(''), 43 | url('../fonts/roboto-mono-v12-latin-regular.woff2') format('woff2'), /* Chrome 26+, Opera 23+, Firefox 39+ */ 44 | url('../fonts/roboto-mono-v12-latin-regular.woff') format('woff'); /* Chrome 6+, Firefox 3.6+, IE 9+, Safari 5.1+ */ 45 | } 46 | /* Regular font */ 47 | body, input { 48 | font-family: 'Roboto', -apple-system, Helvetica, Arial, sans-serif; 49 | } 50 | /* Proportional font */ 51 | pre, code, kbd { 52 | font-family: 'Roboto Mono', SFMono-Regular, Consolas, Menlo, monospace; 53 | } 54 | -------------------------------------------------------------------------------- /de/docs/assets/fonts/roboto-mono-v12-latin-regular.woff: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/openpotato/openplzapi.website/b14265ec347b62cd29364d4a50de92dfd2774454/de/docs/assets/fonts/roboto-mono-v12-latin-regular.woff -------------------------------------------------------------------------------- /de/docs/assets/fonts/roboto-mono-v12-latin-regular.woff2: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/openpotato/openplzapi.website/b14265ec347b62cd29364d4a50de92dfd2774454/de/docs/assets/fonts/roboto-mono-v12-latin-regular.woff2 -------------------------------------------------------------------------------- /de/docs/assets/fonts/roboto-v20-latin-300.woff: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/openpotato/openplzapi.website/b14265ec347b62cd29364d4a50de92dfd2774454/de/docs/assets/fonts/roboto-v20-latin-300.woff -------------------------------------------------------------------------------- /de/docs/assets/fonts/roboto-v20-latin-300.woff2: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/openpotato/openplzapi.website/b14265ec347b62cd29364d4a50de92dfd2774454/de/docs/assets/fonts/roboto-v20-latin-300.woff2 -------------------------------------------------------------------------------- /de/docs/assets/fonts/roboto-v20-latin-700.woff: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/openpotato/openplzapi.website/b14265ec347b62cd29364d4a50de92dfd2774454/de/docs/assets/fonts/roboto-v20-latin-700.woff -------------------------------------------------------------------------------- /de/docs/assets/fonts/roboto-v20-latin-700.woff2: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/openpotato/openplzapi.website/b14265ec347b62cd29364d4a50de92dfd2774454/de/docs/assets/fonts/roboto-v20-latin-700.woff2 -------------------------------------------------------------------------------- /de/docs/assets/fonts/roboto-v20-latin-italic.woff: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/openpotato/openplzapi.website/b14265ec347b62cd29364d4a50de92dfd2774454/de/docs/assets/fonts/roboto-v20-latin-italic.woff -------------------------------------------------------------------------------- /de/docs/assets/fonts/roboto-v20-latin-italic.woff2: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/openpotato/openplzapi.website/b14265ec347b62cd29364d4a50de92dfd2774454/de/docs/assets/fonts/roboto-v20-latin-italic.woff2 -------------------------------------------------------------------------------- /de/docs/assets/fonts/roboto-v20-latin-regular.woff: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/openpotato/openplzapi.website/b14265ec347b62cd29364d4a50de92dfd2774454/de/docs/assets/fonts/roboto-v20-latin-regular.woff -------------------------------------------------------------------------------- /de/docs/assets/fonts/roboto-v20-latin-regular.woff2: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/openpotato/openplzapi.website/b14265ec347b62cd29364d4a50de92dfd2774454/de/docs/assets/fonts/roboto-v20-latin-regular.woff2 -------------------------------------------------------------------------------- /de/docs/assets/logos/favicon.ico: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/openpotato/openplzapi.website/b14265ec347b62cd29364d4a50de92dfd2774454/de/docs/assets/logos/favicon.ico -------------------------------------------------------------------------------- /de/docs/assets/logos/logo.svg: -------------------------------------------------------------------------------- 1 | -------------------------------------------------------------------------------- /de/docs/austria.md: -------------------------------------------------------------------------------- 1 | Das OpenPLZ API-Datenverzeichnis für [Österreich](https://de.wikipedia.org/wiki/%C3%96sterreich) umfasst Straßennamen, Postleitzahlen, Ortsnamen und Verwaltungseinheiten (Gemeinden, Bezirke und Bundeländer). 2 | 3 | ## Verwaltungsstruktur 4 | 5 | Die Verwaltungsstruktur in Österreich basiert auf einer föderalen Ordnung, die in mehrere Ebenen gegliedert ist. Jede Ebene hat klar definierte Kompetenzen und Aufgaben, die durch die Verfassung geregelt sind. 6 | 7 | **Bund** 8 | 9 | : Die oberste Verwaltungseinheit des Staates. Der Bund verfügt über eine zentrale Regierung und ist für übergeordnete Angelegenheiten wie Außenpolitik, Verteidigung und Justiz verantwortlich. 10 | 11 | **Bundesländer** 12 | 13 | : Die föderalen Einheiten unterhalb des Bundes, bestehend aus 9 Bundesländern. Jedes Bundesland hat eine eigene Verfassung, eine Landesregierung und einen Landtag. Die Länder besitzen eigenständige Kompetenzen, insbesondere in Bereichen wie Bildung und Kultur. 14 | 15 | **Bezirke** 16 | 17 | : Eine mittlere Verwaltungsebene zwischen den Ländern und Gemeinden, bestehend aus politischen Bezirken. Bezirke haben keine eigene Gesetzgebung, sondern dienen der Verwaltung von Aufgaben, die über die Gemeindekompetenzen hinausgehen. Bezirksverwaltungsbehörden sind entweder Bezirkshauptmannschaften oder Magistrate in Statutarstädten. 18 | 19 | **Gemeinden** 20 | 21 | : Die kleinste Verwaltungseinheit mit Selbstverwaltungskompetenz. Es gibt rund 2.000 Gemeinden in Österreich. Jede Gemeinde besitzt eine gewählte Gemeindeverwaltung, die von einem Bürgermeister geleitet wird. 22 | 23 | **Statutarstädte** 24 | 25 | : Städte, die sowohl die Aufgaben einer Gemeinde als auch eines Bezirks wahrnehmen. Es gibt 15 Statutarstädte in Österreich, darunter Wien, das zugleich ein Bundesland ist. 26 | 27 | ## Abfrage Bundesländer 28 | 29 | Die neun österreichischen Bundesländer werden über den folgenden API-Endpunkt abgefragt: 30 | 31 | !!! info "" 32 | 33 | **`openplzapi.org/at/FederalProvinces`** 34 | 35 | : Liste aller Bundesländer in Österreich 36 | 37 | Pro Bundesland werden folgende Attribute geliefert: 38 | 39 | + `key (string)`: Bundeslandkennziffer (1-stellig) 40 | + `name (string)`: Name des Bundeslandes 41 | 42 | Hier eine Beispielabfrage für die komplette Liste der Bundesländer: 43 | 44 | ``` 45 | GET https://openplzapi.org/at/FederalProvinces 46 | ``` 47 | 48 | ## Abfrage Bezirke 49 | 50 | Die Abfrage der politischen Bezirke erfolgt über folgenden API-Endpunkt: 51 | 52 | !!! info "" 53 | 54 | **`openplzapi.org/at/FederalProvinces/{Bundeslandkennziffer}/Districts`** 55 | 56 | : Liste aller Bezirke in einem Bundesland. Als Parameter wird die Bundeslandkennziffer (1-stellig) benötigt. Die Abfrage unterliegt einem [Paging](paging.md). 57 | 58 | 59 | Pro Bezirk werden folgende Attribute geliefert: 60 | 61 | + `key (string)`: Bezirkskennziffer (3-stellig) 62 | + `code (string)`: Bezirkskodierung (3-stellig) 63 | + `name (string)`: Bezirksname 64 | + `federalProvince.key (string)`: Bundeslandkennziffer (1-stellig) 65 | + `federalProvince.name (string)`: Name des Bundeslandes 66 | 67 | Hier eine Beispielabfrage für die Liste der Bezirke in Wien (Bundeslandkennziffer: `7`): 68 | 69 | ``` 70 | GET https://openplzapi.org/at/FederalProvinces/7/Districts 71 | ``` 72 | 73 | ## Abfrage Gemeinden 74 | 75 | Die Abfrage der Gemeinden erfolgt über folgende API-Endpunkte: 76 | 77 | !!! info "" 78 | 79 | **`openplzapi.org/at/FederalProvinces/{Bundeslandkennziffer}/Municipalites`** 80 | 81 | : Liste aller Gemeinden in einem Bundesland. Als Parameter wird die Bundeslandkennziffer (1-stellig) benötigt. Die Abfrage unterliegt einem [Paging](paging.md). 82 | 83 | **`openplzapi.org/at/Districts/{Bezirksschlüssel}/Municipalites`** 84 | 85 | : Liste aller Gemeinden in einem Bezirk. Als Parameter wird die Bezirkskennziffer **oder** die Bezirkscodierung (beide 3-stellig) benötigt. Die Abfrage unterliegt einem [Paging](paging.md). 86 | 87 | Pro Gemeinde werden folgende Attribute geliefert: 88 | 89 | + `key (string)`: Gemeindekennziffer (5-stellig) 90 | + `code (string)`: Gemeindecode (5-stellig) 91 | + `name (string)`: Name der Gemeinde 92 | + `status (string)`: Status der Gemeinde. Mögliche Werte: 93 | + `Markt` 94 | + `Kreisfreie Stadt` 95 | + `Stadtkreis` 96 | + `Stadt` 97 | + `Kreisangehörige Gemeinde` 98 | + `Gemeindefreies Gebiet (bewohnt)` 99 | + `Gemeindefreies Gebiet (unbewohnt)` 100 | + `Große Kreisstadt` 101 | + `postalCode (string)`: Postleitzahl des Gemeindeamtes 102 | + `multiplePostalCodes (bool)`: Umfasst die Gemeinde mehr als eine Postleitzahl? 103 | + `district.key (string)`: Bezirkskennziffer (3-stellig) 104 | + `district.code (string)`: Bezirkskodierung (3-stellig) 105 | + `district.name (string)`: Bezirksname 106 | + `federalProvince.key (string)`: Bundeslandkennziffer (1-stellig) 107 | + `federalProvince.name (string)`: Name des Bundeslandes 108 | 109 | Hier eine Beispielabfrage für die Liste der Gemeinden in Wien (Bundeslandkennziffer: `7`): 110 | 111 | ``` 112 | GET https://openplzapi.org/at/FederalProvinces/7/Municipalities 113 | ``` 114 | 115 | ## Abfrage Postleitzahlen und Orte 116 | 117 | Die Abfrage der Postleitzahlen und Orte erfolgt über folgende API-Endpunkte: 118 | 119 | !!! info "" 120 | 121 | **`openplzapi.org/at/FederalProvinces/{Bundeslandkennziffer}/Localities`** 122 | 123 | : Liste aller Orte in einem Bundesland. Als Parameter wird die Bundeslandkennziffer (1-stellig) benötigt. Die Abfrage unterliegt einem [Paging](paging.md). 124 | 125 | **`openplzapi.org/at/Districts/{Bezirksschlüssel}/Localities`** 126 | 127 | : Liste aller Orte in einen Bezirk. Als Parameter wird die Bezirkskennziffer **oder** die Bezirkscodierung (beide 3-stellig) benötigt. Die Abfrage unterliegt einem [Paging](paging.md). 128 | 129 | **`openplzapi.org/at/Localities?postalCode={Postleitzahl}&name={Ortsname}`** 130 | 131 | : Sucht alle Orte, die zur Postleitzahl und/oder zum Ortsnamen passen. Die Parameter `postalCode` und `name` können zusammen oder jeweils exklusiv genutzt werden. Beide Parameter unterstützen auch [regulären Ausdrücke](regex.md). Die Abfrage unterliegt einem [Paging](paging.md). 132 | 133 | Pro Ort werden folgende Attribute geliefert: 134 | 135 | + `key (string)`: Ortschaftskennziffer 136 | + `name (string)`: Name des Ortes 137 | + `postalcode (string)`: Postleitzahl des Ortes 138 | + `municipality.key (string)`: Gemeindekennziffer (5-stellig) 139 | + `municipality.code (string)`: Gemeindecode (5-stellig) 140 | + `municipality.name (string)`: Name der Gemeinde 141 | + `district.key (string)`: Bezirkskennziffer (3-stellig) 142 | + `district.code (string)`: Bezirkskodierung (3-stellig) 143 | + `district.name (string)`: Bezirksname 144 | + `federalProvince.key (string)`: Bundeslandkennziffer (1-stellig) 145 | + `federalProvince.name (string)`: Name des Bundeslandes 146 | 147 | Hier eine Beispielabfrage für die Postleitzahl *1010*: 148 | 149 | ``` 150 | GET https://openplzapi.org/at/Localities?postalCode=1010 151 | ``` 152 | 153 | Hier eine Beispielabfrage für alle deutschen Postleitzahlen, die mit *10* beginnen. Der [reguläre Ausruck](regex.md) `^10` ist [URL-kodiert](url-encoding.md): 154 | 155 | ``` 156 | GET https://openplzapi.org/at/Localities?postalCode=%5E10 157 | ``` 158 | 159 | ## Abfrage Straßen 160 | 161 | Die Abfrage der Straßen erfolgt über folgende API-Endpunkte: 162 | 163 | !!! info "" 164 | 165 | **`openplzapi.org/at/Streets?name={Straßenname}&postalCode={Postleitzahl}&locality={Ortsname}`** 166 | 167 | : Sucht alle Straßen, die zum Straßennamen und/oder der Postleitzahl und/oder zum Ortsnamen passen. Die Parameter `name`, `postalCode` und `locality` können zusammen oder jeweils exklusiv genutzt werden. Alle drei Parameter unterstützen auch [regulären Ausdrücke](regex.md). Die Abfrage unterliegt einem [Paging](paging.md). 168 | 169 | **`openplzapi.org/at/FullTextSearch?searchTerm={Suchbegriff}`** 170 | 171 | : Sucht alle Straßen mittels [Volltextsuche](fulltextsearch.md) über Straßenname, Postleitzahl und Ortsname. Die Abfrage unterliegt einem [Paging](paging.md). 172 | 173 | Pro Straße werden folgende Attribute geliefert: 174 | 175 | + `key (string)`: Straßenkennziffer 176 | + `name (string)`: Name der Straße 177 | + `postalcode (string)`: Postleitzahl des Ortes 178 | + `locality (string)`: Name des Ortes 179 | + `municipality.key (string)`: Gemeindekennziffer (5-stellig) 180 | + `municipality.code (string)`: Gemeindecode (5-stellig) 181 | + `municipality.name (string)`: Name der Gemeinde 182 | + `district.key (string)`: Bezirkskennziffer (3-stellig) 183 | + `district.code (string)`: Bezirkskodierung (3-stellig) 184 | + `district.name (string)`: Bezirksname 185 | + `federalProvince.key (string)`: Bundeslandkennziffer (1-stellig) 186 | + `federalProvince.name (string)`: Name des Bundeslandes 187 | 188 | Hier eine Beispielabfrage für die Straße *Alexander-Poch-Platz*: 189 | 190 | ``` 191 | GET https://openplzapi.org/at/Streets?name=Alexander-Poch-Platz 192 | ``` 193 | 194 | Hier eine Beispielabfrage für alle Plätze in Wien, die mit *A* anfangen und mit *Platz* aufhören. Der [reguläre Ausruck](regex.md) `^A.*Platz$` ist [URL-kodiert](url-encoding.md): 195 | 196 | ``` 197 | GET https://openplzapi.org/at/Streets?name=%5EA.%2APlatz%24&locality=Wien 198 | ``` 199 | 200 | Hier eine Volltextsuche mit dem Suchbegriff `Wien Alfred Dallinger Platz`. Der Suchbegriff ist [URL-kodiert](url-encoding.md): 201 | 202 | ``` 203 | GET https://openplzapi.org/at/FullTextSearch?searchTerm=Wien%20Alfred%20Dallinger%20Platz 204 | ``` -------------------------------------------------------------------------------- /de/docs/change-log-data.md: -------------------------------------------------------------------------------- 1 | # Aktuelle Daten 2 | 3 | Der aktuelle Datenbestand (siehe auch [Datenquellen](sources.md)): 4 | 5 | Land | Datenquelle | Veröffentlichung 6 | ----------------------- | ------------------- | ---------------- 7 | :flag_de: Deutschland | Gemeindeverzeichnis | 29.01.2025 8 | :flag_de: Deutschland | Straßenverzeichnis | 04.03.2025 9 | :flag_li: Liechtenstein | Gemeindeverzeichnis | März 1996 10 | :flag_li: Liechtenstein | Straßenverzeichnis | 04.03.2025 11 | :flag_ch: Schweiz | Gemeindeverzeichnis | 04.03.2025 12 | :flag_ch: Schweiz | Straßenverzeichnis | 04.03.2025 13 | :flag_at: Österreich | Gemeindeverzeichnis | 27.02.2025 14 | :flag_at: Österreich | Straßenverzeichnis | 27.02.2025 15 | -------------------------------------------------------------------------------- /de/docs/change-log-webservice.md: -------------------------------------------------------------------------------- 1 | # Änderungslog - Web-Service 2 | 3 | Der OpenPLZ API Web-Service ist [Open Source](https://github.com/openpotato/openplzapi) unter GitHub. Dort kann die detailierte [Commit-Historie](https://github.com/openpotato/openplzapi/commits/develop/) eingesehen werden. Dieses Änderungslog dient als zusammenfassender Überblick der Änderungen. 4 | 5 | Wir halten uns dabei weitestgehend an die Empfehlungen aus dem Community-Projekt [Keep a Changelog](https://keepachangelog.com/de). 6 | 7 | ## 1.1.0 _ 5. März 2025 8 | 9 | **Geändert:** 10 | 11 | + Quelle für GV100AD aktualisiert 12 | + Abhängigkeiten aktualisiert 13 | + Kleinere Refactorings 14 | 15 | ## 1.0.0 _ 16. Dezember 2024 16 | 17 | **Hinzugefügt:** 18 | 19 | + HTTP Access-Control-Expose-Headers response header hinzugefügt 20 | 21 | **Geändert:** 22 | 23 | + Breaking API change: Fehlender Paging-Endpunkt für `at/Districts/{key}/Localities` implementiert. 24 | 25 | **Korrigiert:** 26 | 27 | + Fehlerhaftes CSV-Antwortformat für Schweizer Daten korrigiert. 28 | 29 | ## 0.1.0 _ 02. Dezember 2024 30 | 31 | **Geändert:** 32 | 33 | + Update auf .NET 9. 34 | + Breaking API change: Gemeinden, Bezirke und Kantone für die Schweiz haben jetzt alle die Eigenschaften `HistoricalCode` und `ShortName` hinzubekommen. Die Eigenschaft `Code` bei Kantonen wurde dafür gestrichen. 35 | + Refactoring der Quelle für das Gemeindeverzeichniss der Schweiz. Es wird jetzt direkt auf die API des Bundesamt für Statistik (BFS) zugegriffen 36 | 37 | ## 0.0.6 _ 25. November 2024 38 | 39 | **Hinzugefügt:** 40 | 41 | + Neue API-Endpunkte `FullTextSearch` zur Volltextsuche über Straße, Ort und Postleitzahl für alle Länder. 42 | + Zusätzliche Paging-Informationen `x-page`, `x-page-size`, `x-total-pages`und `x-total-count` in den HTTP-Response-Headers der API-Antworten (gilt nur für Endpunkte mit Pagination). 43 | + Support für [RFC 9457](https://www.rfc-editor.org/rfc/rfc9457) (Problem Details for HTTP APIs) 44 | 45 | **Korrigiert:** 46 | 47 | + Fehlerhafte URL für API-Endpunkt `li/Communes` korrigiert (war zuvor `li/Cantons/Communes`). 48 | 49 | ## 0.0.5 _ 20. September 2024 50 | 51 | **Hinzugefügt:** 52 | 53 | + `Street`-Entitäten für Deutschland enthalten jetzt zusätzliche Angaben zu Stadtbezirk (Borough) und/oder Stadtteil (Suburb) (soweit in OpenStreetMap vorhanden). 54 | + Support für Straßen und Postleitzahlen aus Liechtenstein. 55 | 56 | **Geändert:** 57 | 58 | + Aktualisierung der Datenquellen. 59 | 60 | ## 0.0.4 _ 23. November 2023 61 | 62 | **Hinzugefügt:** 63 | 64 | + Neue API-Endpunkte für `Locality`-Entitäten. 65 | + Pagination für fast alle API-Endpunkte. 66 | 67 | **Geändert:** 68 | 69 | + Update auf .NET 8. 70 | 71 | ## 0.0.3 _ 27. September 2023 72 | 73 | **Hinzugefügt:** 74 | 75 | + CSV als zusätzliches Ausgabeformat. 76 | 77 | **Geändert:** 78 | 79 | + Aktualisierung der Datenquellen. 80 | 81 | ## 0.0.2 _ 05. Februar 2023 82 | 83 | **Hinzugefügt:** 84 | 85 | + `Street`-Entitäten und `Locality`-Entitäten enthalten jetzt ausführlichere Angaben zu Gemeinden, Kreisen, Bezirken und Bundesländern bzw. Kantonen. 86 | + [CORS](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS)-Unterstützung hinzugefügt. 87 | 88 | ## 0.0.1 _ 09. Dezember 2022 89 | 90 | Erste Veröffentlichung. -------------------------------------------------------------------------------- /de/docs/community.md: -------------------------------------------------------------------------------- 1 | # Community 2 | 3 | OpenPLZ API ist Open Data, die Infrastruktur Open Source. Ein Projekt wie dieses lebt von den Nutzern, die es nutzen. Wie freuen uns über Feedback und Hilfe jeglicher Art: 4 | 5 | + Ein Frage oder Meldung im [GitHub Issue Tracker](https://github.com/openpotato/openplzapi/issues) erstellen. 6 | + Eine Diskussion unter [GitHub Discussions](https://github.com/openpotato/openplzapi.website/discussions) starten. 7 | + Einen [Pull-Request](https://github.com/openpotato/openplzapi/pulls) initiieren. 8 | -------------------------------------------------------------------------------- /de/docs/errors.md: -------------------------------------------------------------------------------- 1 | # Fehlermeldungen 2 | 3 | Die OpenPLZ API liefert Fehlermeldungen als RFC 9457-formatierte JSON-Objekte zurück. 4 | 5 | ## Was ist RFC 9457? 6 | 7 | [RFC 9457](https://www.rfc-editor.org/rfc/rfc9457) ist ein Standard der Internet Engineering Task Force (IETF), der ein strukturiertes Format zur Darstellung von Fehlern in HTTP-APIs definiert. 8 | 9 | ## Problem Details 10 | 11 | Im Zentrum von RFC 9457 steht das *Problem Details*-Objekt, ein JSON-Dokument, das bei Fehlern im Response-Body der API-Abfrage enthalten ist. OpenPLZ API implementiert es mit folgenden Feldern: 12 | 13 | `type` (string) 14 | 15 | : Eine URI-Referenz, die den Typ des Fehlers identifiziert. Dies ist in der Regel ein Verweis auf die Spezifikation des HTTP-Statuscodes im Web. 16 | 17 | Beispiel: `"https://tools.ietf.org/html/rfc9110#section-15.5.1"` 18 | 19 | `title` (string) 20 | 21 | : Eine kurze, menschenlesbare Zusammenfassung des Problems. 22 | 23 | Beispiel: `"One or more validation errors occurred."` 24 | 25 | `status` (integer) 26 | 27 | : Der HTTP-Statuscode, der den Fehler beschreibt. Er sollte mit dem Statuscode im HTTP-Response-Header übereinstimmten. 28 | 29 | Beispiel: 400 30 | 31 | `errors` (object) 32 | 33 | : (Optional) Eine JSON-Objekt mit weiteren Details zum Fehler. 34 | 35 | Beispiel: 36 | ``` 37 | { 38 | "pageSize": [ 39 | "The field pageSize must be between 1 and 50." 40 | ] 41 | } 42 | ``` 43 | 44 | `traceId` (string) 45 | 46 | : Ein eindeutiger Identifikator, der zur Nachverfolgung in verteilten Systemen genutzt werden kann. 47 | 48 | Beispiel: `"00-abc123def456789ghi-xyz987uvw654321tqr-01"` 49 | 50 | !!! note "Extension Members" 51 | 52 | Die Felder `type`, `title` und `status` sind wohldefiniert in RFC 9457. Die Felder `errors` und `traceId` sind sogenannte *Extension Members*, also eine Erweiterung der Standardfelder. 53 | 54 | ## Beispiel 55 | 56 | Der API-Aufruf 57 | 58 | ``` 59 | https://openplzapi.org/de/Streets?name=Pariser%20Platz&locality=Berlin&page=1&pageSize=99 60 | ``` 61 | 62 | resultiert in folgender Fehlermeldung: 63 | 64 | ``` json 65 | { 66 | "type": "https://tools.ietf.org/html/rfc9110#section-15.5.1", 67 | "title": "One or more validation errors occurred.", 68 | "status": 400, 69 | "errors": { 70 | "pageSize": [ 71 | "The field pageSize must be between 1 and 50." 72 | ] 73 | }, 74 | "traceId": "00-0274bb16dcdf462bf27a7faedeacc79f-05c5cd5b5d411f8e-00" 75 | } 76 | ``` 77 | 78 | Die Analyse des Fehlers: 79 | 80 | + Der Server kann die Anfrage nicht bearbeiten, da der Aufruf nicht korrekt formuliert ist (HTTP-Fehler-Code 400: Bad Request). 81 | 82 | + Offensichtlich ist etwas bei der Validierung der Aufrufparameter passiert ("One or more validation errors occurred."). 83 | 84 | + Und ja, so ist es auch, der Parameter `pageSize` hat einen Wert (99) außerhalb der Gültigkeit (nur von 1-50). 85 | -------------------------------------------------------------------------------- /de/docs/faq.md: -------------------------------------------------------------------------------- 1 | # Häufig gestellte Fragen (FAQ) 2 | 3 | Ist die OpenPLZ API wirklich kostenlos? Woher stammen die ganzen Daten? In unseren FAQ erhältst Du Antworten auf die am häufigsten gestellten Fragen zum OpenPLZ API Projekt. 4 | 5 | ## Kann ich die OpenPLZ API kostenfrei nutzen? 6 | 7 | Ja, das OpenPLZ API-Projekt ist Open Data, die Nutzung ist kostenfrei und auch in kommerziellen Projekten erlaubt. Alle Daten stammen aus öffentlichen Quellen und sind [hier dokumentiert](sources.md). Die aufbereiteten Daten sind unter der [ODC Open Database License (ODbL)](https://raw.githubusercontent.com/openpotato/openplzapi.data/refs/heads/main/LICENSE) lizenziert. 8 | 9 | ## Wo ist die OpenPLZ API gehostet? 10 | 11 | Der OpenPLZ API-Webservice läuft auf einem Linux-Server, der vom deutschen Internetdienstanbieter [STRATO](https://www.strato.de/) betrieben wird. Der Standort des Rechenzentrums ist Deutschland. 12 | 13 | ## Woher stammen die Daten? 14 | 15 | Alle Daten des OpenPLZ API-Projekts stammen aus öffentlichen Quellen und sind [hier dokumentiert](sources.md). Die aufbereiteten Daten stehen unter der [ODC Open Database License (ODbL)](https://raw.githubusercontent.com/openpotato/openplzapi.data/refs/heads/main/LICENSE) zur Verfügung. 16 | 17 | ## Wie oft wird aktualisiert? 18 | 19 | Die Daten des OpenPLZ API-Projekts werden regelmäßig aktualisiert. Zur Zeit streben wir eine vierteljährliche Aktualisierung an. Der aktuelle Stand der Daten wird stets im [Änderungslog](change-log-data.md) dokumentiert. 20 | 21 | ## Ich habe einen Fehler gefunden! 22 | 23 | Bitte gib uns Bescheid. Am besten via [GitHub-Issue-Tracker](https://github.com/openpotato/openplzapi/issues). 24 | 25 | ## Ich will mitmachen! 26 | 27 | Du hast einen Vorschlag zur Verbesserung? Immer her damit, am Besten als Diskussionsbeitrag unter [GitHub](https://github.com/openpotato/openplzapi.website/discussions). 28 | 29 | Noch besser, Du hast einen Fehler korrigiert oder eine Verbesserung programmiert? Prima, wir warten auf Deinen [Pull-Request unter GitHub](https://github.com/openpotato/openplzapi/pulls). 30 | 31 | ## Noch Fragen? 32 | 33 | Du kannst uns jederzeit fragen. Nutze dafür den [GitHub-Issue-Tracker](https://github.com/openpotato/openplzapi/issues). Du willst uns lieber eine E-Mail schreiben? Gerne, schreib uns an `openpotato@stueber.de`. 34 | -------------------------------------------------------------------------------- /de/docs/fulltextsearch.md: -------------------------------------------------------------------------------- 1 | # Volltextsuche 2 | 3 | Für jedes im OpenPLZ API-Projekt unterstützte Land existiert ein spezieller API-Endpunkt zur **Volltextsuche**. 4 | 5 | ## Was ist Volltextsuche? 6 | 7 | Die Volltextsuche in relationalen Datenbanken ermöglicht das Durchsuchen von Texten in einer oder mehreren Spalten auf der Grundlage der tatsächlichen Bedeutung der Wörter anstatt eines einfachen Zeichenfolgenabgleichs. Das Ziel ist, möglichst relevante Ergebnisse zurückzuliefern, wenn nach bestimmten Begriffen gesucht wird – ähnlich wie bei einer Suchmaschine. 8 | 9 | Wer z.B. nach `Monchengladbach` sucht, der bekommt auch Ergebnisse zu `Mönchengladbach` zurückgeliefert. 10 | 11 | Zudem kann man bei der Eingabe Straße, Postleitzahl und/oder Ort in beliebiger Reihenfolge eintippen. Die Sucheingabe 12 | 13 | ``` 14 | Berlin Pariser Platz 15 | ``` 16 | 17 | liefert das gleiche Ergebnis wie 18 | 19 | ``` 20 | Pariser Platz, Berlin 21 | ``` 22 | 23 | ## Wie genau funktioniert die Volltextsuche? 24 | 25 | Wir nutzen die Volltextsuche von PostgreSQL im Hintergrund, genauer gesagt die Funktion [`websearch_to_tsquery`](https://www.postgresql.org/docs/current/textsearch-controls.html#TEXTSEARCH-PARSING-QUERIES). Diese Funktion erlaubt die Eingabe von unformatierten Text und konvertiert diesen in das passende Zielformat für PostgreSQL: 26 | 27 | + Text, der nicht in Anführungszeichen steht, wird in Begriffe umgewandelt, die durch `&`-Operatoren getrennt sind, wie bei der Verarbeitung durch `plainto_tsquery`. 28 | 29 | + Text in "Anführungszeichen" wird in Begriffe umgewandelt, die durch `<->`-Operatoren getrennt sind, als ob sie von `phraseto_tsquery` verarbeitet würden. 30 | 31 | + Ein `OR` wird in den Operator `|` umgewandelt. 32 | 33 | + Ein Bindestrich `-` wird in den Operator `!` umgewandelt. 34 | 35 | + Sonstige Sonderzeichen, wie z.B. Punkt, Komma, Ausrufezeichen etc. werden ignoriert. 36 | 37 | ## Wo finde ich die Volltextsuche? 38 | 39 | Die folgenden API-Endpunkte erlauben jeweils die Volltextsuche über Straßenname, Postleitzahl und Ortsname: 40 | 41 | + `at/FullTextSearch` 42 | + `ch/FullTextSearch` 43 | + `de/FullTextSearch` 44 | + `li/FullTextSearch` 45 | 46 | Am besten einfach ausprobieren. 47 | 48 | 49 | 50 | -------------------------------------------------------------------------------- /de/docs/germany.md: -------------------------------------------------------------------------------- 1 | Das OpenPLZ API-Datenverzeichnis für [Deutschland](https://de.wikipedia.org/wiki/Deutschland) umfasst Straßennamen, Postleitzahlen, Ortsnamen und Verwaltungseinheiten (Gemeinden, Gemeindeverbände, Kreise, Regierungsbezirke und Bundesländer). 2 | 3 | ## Verwaltungsstruktur 4 | 5 | Die Verwaltungsstruktur in Deutschland basiert auf einem föderalen System, das durch das Grundgesetz geregelt ist. Sie gliedert sich in mehrere Ebenen mit jeweils spezifischen Kompetenzen und Aufgaben. 6 | 7 | **Bund** 8 | 9 | : Die oberste Ebene der Verwaltung und Gesetzgebung in Deutschland. Der Bund ist zuständig für übergeordnete Angelegenheiten wie Außenpolitik, Verteidigung und die Währungsordnung. Die Legislative wird durch den Bundestag und den Bundesrat, die Exekutive durch die Bundesregierung gebildet. 10 | 11 | **Bundesländer** 12 | 13 | : Die föderalen Einheiten unterhalb des Bundes, bestehend aus 16 Bundesländern. Jedes Bundesland besitzt eine eigene Verfassung, eine Landesregierung und einen Landtag. Die Länder haben eigene Zuständigkeiten, insbesondere in Bereichen wie Bildung, Polizei und Kultur. 14 | 15 | **Regierungsbezirke** 16 | 17 | : Eine mittlere Verwaltungsebene, die in einigen Bundesländern zwischen der Landes- und Kreisebene angesiedelt ist. Regierungsbezirke existieren nur noch in vier der 16 Bundesländer und dienen der Koordination der Landesverwaltung. Sie haben keine eigenständige Gesetzgebung. 18 | 19 | **Kreise** 20 | 21 | : Eine kommunale Verwaltungseinheit, die zwischen den Regierungsbezirken (sofern vorhanden) und den Gemeinden liegt. 22 | 23 | Die wichtigsten Arten: 24 | 25 | + Landkreise 26 | + Kreisfreie Städte (nehmen die Aufgaben von Kreisen und Gemeinden gleichzeitig wahr). 27 | 28 | **Gemeinden** 29 | 30 | : Die kleinste Verwaltungseinheit mit umfassenden Selbstverwaltungsrechten. Gemeinden sind für die unmittelbare Verwaltung vor Ort zuständig. Sie verfügen über einen gewählten Gemeinderat und meist einen Bürgermeister als Verwaltungsleitung. 31 | 32 | **Gemeindeverbände** 33 | 34 | : Zusammenschlüsse von Gemeinden zur gemeinsamen Erfüllung bestimmter Aufgaben. Gemeindeverbände, wie Verwaltungsgemeinschaften oder Zweckverbände, sind in der Regel auf spezifische administrative Funktionen begrenzt. 35 | 36 | ## Abfrage Bundesländer 37 | 38 | Die Abfrage der 16 deutschen Bundesländer erfolgt über folgenden API-Endpunkt: 39 | 40 | !!! info "" 41 | 42 | **`openplzapi.org/de/FederalStates`** 43 | 44 | : Liste aller Bundesländer in Deutschland 45 | 46 | Pro Bundesland werden folgende Attribute geliefert: 47 | 48 | + `key (string)`: Regionalschlüssel (2-stellig) 49 | + `name (string)`: Name des Bundeslandes 50 | + `seatOfGovernment (string)`: Regierungssitz des Bundeslandes 51 | 52 | Hier eine Beispielabfrage für die komplette Liste der Bundesländer: 53 | 54 | ``` 55 | GET https://openplzapi.org/de/FederalStates 56 | ``` 57 | 58 | ## Abfrage Regierungsbezirke 59 | 60 | Die Abfrage der Regierungsbezirke erfolgt über folgenden API-Endpunkt: 61 | 62 | !!! info "" 63 | 64 | **`openplzapi.org/de/FederalStates/{Bundeslandschlüssel}/GovernmentRegions`** 65 | 66 | : Liste aller Regierungsbezirke in einem Bundesland. Als Parameter wird ein Bundeslandschlüssel (2-stellig) benötigt. Die Abfrage unterliegt einem [Paging](paging.md). 67 | 68 | Pro Regierungsbezirk werden folgende Attribute geliefert: 69 | 70 | + `key (string)`: Regionalschlüssel (3-stellig) 71 | + `name (string)`: Name des Regierungsbezirks 72 | + `administrativeHeadquarters (string)`: Verwaltungssitz des Regierungsbezirks 73 | + `federalState.key (string)`: Regionalschlüssel des Bundeslandes (2-stellig) 74 | + `federalState.name (string)`: Name des Bundeslandes 75 | 76 | !!! note "Regierungsbezirke" 77 | 78 | Bitte beachte, dass es nur noch in vier Bundesländern Regierungsbezirke gibt: **Baden-Württemberg**, **Bayern**, **Hessen** und **Nordrhein-Westfalen**. In den Bundesländern **Niedersachen**, **Rheinland-Pfalz** und **Sachsen** sind die Regierungsbezirke offiziell abgeschafft, werden aber aus statistischen Gründen noch weiter im Gemeindeverzeichnis geführt und sind damit auch hier noch abrufbar. 79 | 80 | Hier eine Beispielabfrage für die Liste der Regierungsbezirke in Bayern (Bundeslandschlüssel: `09`): 81 | 82 | ``` 83 | GET https://openplzapi.org/de/FederalStates/09/GovernmentRegions 84 | ``` 85 | 86 | ## Abfrage Kreise 87 | 88 | Die Abfrage der Kreise erfolgt über folgende API-Endpunkte: 89 | 90 | !!! info "" 91 | 92 | **`openplzapi.org/de/FederalStates/{Bundeslandschlüssel}/Districts`** 93 | 94 | : Liste aller Kreise in einem Bundesland. Als Parameter wird ein Bundeslandschlüssel (2-stellig) benötigt. Die Abfrage unterliegt einem [Paging](paging.md). 95 | 96 | **`openplzapi.org/de/GovernmentRegions/{Bezirksschlüssel}/Districts`** 97 | 98 | : Liste aller Kreise in einem Regierungsbezirk. Als Parameter wird ein Bezirksschlüssel (3-stellig) benötigt. Die Abfrage unterliegt einem [Paging](paging.md). 99 | 100 | Pro Kreis werden folgende Attribute geliefert: 101 | 102 | + `key (string)`: Regionalschlüssel (5-stellig) 103 | + `name (string)`: Name des Kreises 104 | + `type (string)`: Kennzeichen des Kreises. Mögliche Werte: 105 | + `Kreisfreie Stadt` 106 | + `Stadtkreis` 107 | + `Kreis` 108 | + `Landkreis` 109 | + `Regionalverband` 110 | + `administrativeHeadquarters (string)`: Sitz der Kreisverwaltung 111 | + `governmentRegion.key (string)`: Regionalschlüssel des Regierungsbezirks (3-stellig) 112 | + `governmentRegion.name (string)`: Name des Regierungsbezirks 113 | + `federalState.key (string)`: Regionalschlüssel des Bundeslandes (2-stellig) 114 | + `federalState.name (string)`: Name des Bundeslandes 115 | 116 | Hier eine Beispielabfrage für die Liste der Kreise in Rheinland-Pfalz (Bundeslandschlüssel: `07`): 117 | 118 | ``` 119 | GET https://openplzapi.org/de/FederalStates/07/Districts 120 | ``` 121 | 122 | ## Abfrage Gemeinden 123 | 124 | Die Abfrage der Gemeinden erfolgt über folgende API-Endpunkte: 125 | 126 | !!! info "" 127 | 128 | **`openplzapi.org/de/FederalStates/{Bundeslandschlüssel}/Municipalites`** 129 | 130 | : Liste aller Gemeinden in einem Bundesland. Als Parameter wird ein Bundeslandschlüssel (2-stellig) benötigt. Die Abfrage unterliegt einem [Paging](paging.md). 131 | 132 | **`openplzapi.org/de/GovernmentRegions/{Bezirksschlüssel}/Municipalites`** 133 | 134 | : Liste aller Gemeinden in einem Regierungsbezirk. Als Parameter wird ein Bezirksschlüssel (3-stellig) benötigt. Die Abfrage unterliegt einem [Paging](paging.md). 135 | 136 | **`openplzapi.org/de/Districts/{Kreisschlüssel}/Municipalites`** 137 | 138 | : Liste aller Gemeinden in einen Kreis. Als Parameter wird ein Kreisschlüssel (5-stellig) benötigt. Die Abfrage unterliegt einem [Paging](paging.md). 139 | 140 | Pro Gemeinde werden folgende Attribute geliefert: 141 | 142 | + `key (string)`: Regionalschlüssel (8-stellig) 143 | + `name (string)`: Name der Gemeinde 144 | + `type (string)`: Kennzeichen der Gemeinde. Mögliche Werte: 145 | + `Markt` 146 | + `Kreisfreie Stadt` 147 | + `Stadtkreis` 148 | + `Stadt` 149 | + `Kreisangehörige Gemeinde` 150 | + `Gemeindefreies Gebiet (bewohnt)` 151 | + `Gemeindefreies Gebiet (unbewohnt)` 152 | + `Große Kreisstadt` 153 | + `postalCode (string)`: Postleitzahl des Verwaltungssitzes, falls mehrere Postleitzahlen vorhanden sind 154 | + `multiplePostalCodes (bool)`: Umfasst die Gemeinde mehr als eine Postleitzahl? 155 | + `association.key (string)`: Kombination aus Regionalschlüssel des Kreises und Schlüssel des Gemeindenverbandes (8-stellig) 156 | + `association.name (string)`: Name des Gemeindenverbandes 157 | + `district.key (string)`: Regionalschlüssel des Kreises (5-stellig) 158 | + `district.name (string)`: Name des Kreises 159 | + `governmentRegion.key (string)`: Regionalschlüssel des Regierungsbezirks (3-stellig) 160 | + `governmentRegion.name (string)`: Name des Regierungsbezirks 161 | + `federalState.key (string)`: Regionalschlüssel des Bundeslandes (2-stellig) 162 | + `federalState.name (string)`: Name des Bundeslandes 163 | 164 | Hier eine Beispielabfrage für die Liste der Gemeinden in Rheinland-Pfalz (Bundeslandschlüssel: `07`): 165 | 166 | ``` 167 | GET https://openplzapi.org/de/FederalStates/07/Municipalites 168 | ``` 169 | 170 | ## Abfrage Gemeindenverbände 171 | 172 | Die Abfrage der Gemeindenverbände erfolgt über folgende API-Endpunkte: 173 | 174 | !!! info "" 175 | 176 | **`openplzapi.org/de/FederalStates/{Bundeslandschlüssel}/MunicipalAssociations`** 177 | 178 | : Liste aller Gemeindeverbände in einem Bundesland. Als Parameter wird ein Bundeslandschlüssel (2-stellig) benötigt. Die Abfrage unterliegt einem [Paging](paging.md). 179 | 180 | **`openplzapi.org/de/GovernmentRegions/{Bezirksschlüssel}/MunicipalAssociations`** 181 | 182 | : Liste aller Gemeindeverbände in einem Regierungsbezirk. Als Parameter wird ein Bezirksschlüssel (3-stellig) benötigt. Die Abfrage unterliegt einem [Paging](paging.md). 183 | 184 | **`openplzapi.org/de/Districts/{Kreisschlüssel}/MunicipalAssociations`** 185 | 186 | : Liste aller Gemeindeverbände in einen Kreis. Als Parameter wird ein Kreisschlüssel (5-stellig) benötigt. Die Abfrage unterliegt einem [Paging](paging.md). 187 | 188 | Pro Gemeindeverband werden folgende Attribute geliefert: 189 | 190 | + `key (string)`: Kombination aus Regionalschlüssel des Kreises und Schlüssel des Gemeindenverbandes (8-stellig) 191 | + `name (string)`: Name des Gemeindenverbandes 192 | + `type (string)`: Kennzeichen des Gemeindenverbandes. Mögliche Werte: 193 | + `Amt` 194 | + `Samtgemeinde` 195 | + `Verbandsgemeinde` 196 | + `Verwaltungsgemeinschaft` 197 | + `Kirchspielslandgemeinde` 198 | + `Verwaltungsverband` 199 | + `VG Trägermodell` 200 | + `Erfüllende Gemeinde` 201 | + `administrativeHeadquarters (string)`: Verwaltungssitz des Gemeindeverbandes 202 | + `district.key (string)`: Regionalschlüssel des Kreises (5-stellig) 203 | + `district.name (string)`: Name des Kreises 204 | + `governmentRegion.key (string)`: Regionalschlüssel des Regierungsbezirks (3-stellig) 205 | + `governmentRegion.name (string)`: Name des Regierungsbezirks 206 | + `federalState.key (string)`: Regionalschlüssel des Bundeslandes (2-stellig) 207 | + `federalState.name (string)`: Name des Bundeslandes 208 | 209 | Hier eine Beispielabfrage für die Liste der Gemeindenverbände in Bayern (Schlüssel: `09`): 210 | 211 | ``` 212 | https://openplzapi.org/de/FederalStates/09/GovernmentRegions 213 | ``` 214 | 215 | ## Abfrage Postleitzahlen und Orte 216 | 217 | Die Abfrage der Postleitzahlen und Orte erfolgt über folgende API-Endpunkte: 218 | 219 | !!! info "" 220 | 221 | **`openplzapi.org/de/FederalStates/{key}/Localities`** 222 | 223 | : Liste aller Orte in einem Bundesland. Als Parameter wird ein Bundeslandschlüssel (2-stellig) benötigt. Die Abfrage unterliegt einem [Paging](paging.md). 224 | 225 | **`openplzapi.org/de/GovernmentRegions/{Bezirksschlüssel}/Localities`** 226 | 227 | : Liste aller Orte in einem Regierungsbezirk. Als Parameter wird ein Bezirksschlüssel (3-stellig) benötigt. Die Abfrage unterliegt einem [Paging](paging.md). 228 | 229 | **`openplzapi.org/de/Districts/{Kreisschlüssel}/Localities`** 230 | 231 | : Liste aller Orte in einen Kreis. Als Parameter wird ein Kreisschlüssel (5-stellig) benötigt. Die Abfrage unterliegt einem [Paging](paging.md). 232 | 233 | **`openplzapi.org/de/Localities?postalCode={Postleitzahl}&name={Ortsname}`** 234 | 235 | : Sucht alle Orte, die zur Postleitzahl und/oder zum Ortsnamen passen. Die Parameter `postalCode` und `name` können zusammen oder jeweils exklusiv genutzt werden. Beide Parameter unterstützen auch [regulären Ausdrücke](regex.md). Die Abfrage unterliegt einem [Paging](paging.md). 236 | 237 | Pro Ort werden folgende Attribute geliefert: 238 | 239 | + `name (string)`: Name des Ortes 240 | + `postalcode (string)`: Postleitzahl des Ortes 241 | + `municipality.key (string)`: Regionalschlüssel der Gemeinde (8-stellig) 242 | + `municipality.name (string)`: Name der Gemeinde 243 | + `district.key (string)`: Regionalschlüssel des Kreises (5-stellig) 244 | + `district.name (string)`: Name des Kreises 245 | + `governmentRegion.key (string)`: Regionalschlüssel des Regierungsbezirks (3-stellig) 246 | + `governmentRegion.name (string)`: Name des Regierungsbezirks 247 | + `federalState.key (string)`: Regionalschlüssel des Bundeslandes (2-stellig) 248 | + `federalState.name (string)`: Name des Bundeslandes 249 | 250 | Hier eine Beispielabfrage für die Postleitzahl *13156*: 251 | 252 | ``` 253 | GET https://openplzapi.org/de/Localities?postalCode=13156 254 | ``` 255 | 256 | Hier eine Beispielabfrage für alle deutschen Postleitzahlen, die mit *13* beginnen. Der reguläre Ausruck `^13` ist [URL-kodiert](url-encoding.md): 257 | 258 | ``` 259 | GET https://openplzapi.org/de/Localities?postalCode=%5E13 260 | ``` 261 | 262 | ## Abfrage Straßen 263 | 264 | Die Abfrage der Straßen erfolgt über folgende API-Endpunkte: 265 | 266 | !!! info "" 267 | 268 | **`openplzapi.org/de/Streets?name={Straßenname}&postalCode={Postleitzahl}&locality={Ortsname}`** 269 | 270 | : Sucht alle Straßen, die zum Straßennamen und/oder der Postleitzahl und/oder zum Ortsnamen passen. Die Parameter `name`, `postalCode` und `locality` können zusammen oder jeweils exklusiv genutzt werden. Alle drei Parameter unterstützen auch [regulären Ausdrücke](regex.md). Die Abfrage unterliegt einem [Paging](paging.md). 271 | 272 | **`openplzapi.org/de/FullTextSearch?searchTerm={Suchbegriff}`** 273 | 274 | : Sucht alle Straßen mittels [Volltextsuche](fulltextsearch.md) über Straßenname, Postleitzahl und Ortsname. Die Abfrage unterliegt einem [Paging](paging.md). 275 | 276 | Pro Straße werden folgende Attribute geliefert: 277 | 278 | + `name (string)`: Name der Straße 279 | + `postalcode (string)`: Postleitzahl des Ortes 280 | + `locality (string)`: Name des Ortes 281 | + `borough (string)`: Falls vorhanden, Name des Stadtbezirks oder Stadtteils 282 | + `suburb (string)`: Falls vorhanden, Name des Ortsteils 283 | + `municipality.key (string)`: Regionalschlüssel der Gemeinde (8-stellig) 284 | + `municipality.name (string)`: Name der Gemeinde 285 | + `district.key (string)`: Regionalschlüssel des Kreises (5-stellig) 286 | + `district.name (string)`: Name des Kreises 287 | + `governmentRegion.key (string)`: Regionalschlüssel des Regierungsbezirks (3-stellig) 288 | + `governmentRegion.name (string)`: Name des Regierungsbezirks 289 | + `federalState.key (string)`: Regionalschlüssel des Bundeslandes (2-stellig) 290 | + `federalState.name (string)`: Name des Bundeslandes 291 | 292 | Hier eine Beispielabfrage für die Straße *Grabbeallee* (gibt es nur einmal in Berlin): 293 | 294 | ``` 295 | GET https://openplzapi.org/de/Streets?name=Grabbeallee 296 | ``` 297 | 298 | Hier eine Beispielabfrage für alle Straßen in Berlin, die mit *G* anfängen und mit *allee* aufhören. Der reguläre Ausruck `^G.*allee$` ist [URL-kodiert](url-encoding.md): 299 | 300 | ``` 301 | GET https://openplzapi.org/de/Streets?name=%5EG.*allee%24&locality=Berlin 302 | ``` 303 | 304 | Hier eine Volltextsuche mit dem Suchbegriff `Berlin Pariser Platz`. Der Suchbegriff ist [URL-kodiert](url-encoding.md): 305 | 306 | ``` 307 | GET https://openplzapi.org/de/FullTextSearch?searchTerm=Berlin%20Pariser%20Platz 308 | ``` -------------------------------------------------------------------------------- /de/docs/index.md: -------------------------------------------------------------------------------- 1 | **OpenPLZ API** ist ein [Open Data-Projekt](https://opendatahandbook.org/guide/de/what-is-open-data/), das ein öffentliches Strassen- und Postleitzahlverzeichnis für Deutschland, Liechtenstein, die Schweiz und Österreich über eine offene REST-API-Schnittstelle verfügbar macht. Folgende Daten sind abrufbar: 2 | 3 | **:flag_de: Deutschland:** 4 | 5 | + Straßenname 6 | + Postleitzahl und Ort 7 | + Gemeinde (inklusive Angaben zu Kreis, Regierungsbezirk und Bundesland) 8 | 9 | **:flag_li: Liechtenstein:** 10 | 11 | + Straßenname 12 | + Postleitzahl und Ort 13 | + Gemeinde 14 | 15 | **:flag_ch: Schweiz:** 16 | 17 | + Straßenname 18 | + Postleitzahl und Ort 19 | + Gemeinde (inklusive Angaben zu Bezirk und Kanton) 20 | 21 | **:flag_at: Österreich:** 22 | 23 | + Straßenname 24 | + Postleitzahl und Ort 25 | + Gemeinde (inklusive Angaben zu Bezirk und Bundesland) 26 | 27 | ## Los geht's 28 | 29 | Der einfachste Weg, die API zu nutzen, ist der Weg über die Kommandozeile. Wir werden in diesem Kapitel und weiteren Kapiteln mit der Kommandozeilenanwendung [curl](https://curl.se/) arbeiten. 30 | 31 | Unter Linux ist `curl` in der Regel vorinstalliert. Unter Windows ist `curl` als Alias des Cmdlet [Invoke-WebRequest](https://docs.microsoft.com/en-us/powershell/module/microsoft.powershell.utility/invoke-webrequest) definiert, kann also via Powershell genutzt werden. Die hier verwendeten Befehlsfolgen variieren leicht, daher werden sie für Powershell 7 (Windows) und Bash (Linux) getrennt angegeben. 32 | 33 | ### Verwaltungseinheiten 34 | 35 | Pro Land können subnationale Verwaltungseinheiten (z.B. Bundesländer, Schweizer Kantone, Bezirke, Kreise oder Gemeinden) abgefragt werden. Grundlage für die Filterung ist stets der offizielle Schlüssel (key) der Verwaltungseinheit. 36 | 37 | Hier eine Beispielabfrage für die Liste der deutschen Bundesländer: 38 | 39 | === "Powershell 7" 40 | 41 | ``` powershell 42 | curl -X GET 'https://openplzapi.org/de/FederalStates' -H 'accept: text/json' | ConvertFrom-Json | ConvertTo-Json 43 | ``` 44 | 45 | === "Bash" 46 | 47 | ``` bash 48 | curl -X GET 'https://openplzapi.org/de/FederalStates' -H 'accept: text/json' | json_pp 49 | ``` 50 | 51 | Hier eine Beispielabfrage für die Liste aller österreichischen Gemeinden im Bundesland *Niederösterreich* (Schlüssel "3"): 52 | 53 | === "Powershell 7" 54 | 55 | ``` powershell 56 | curl -X GET 'https://openplzapi.org/at/FederalProvinces/3/Municipalities' -H 'accept: text/json' | ConvertFrom-Json | ConvertTo-Json 57 | ``` 58 | 59 | === "Bash" 60 | 61 | ``` bash 62 | curl -X GET 'https://openplzapi.org/at/FederalProvinces/3/Municipalities' -H 'accept: text/json' | json_pp 63 | ``` 64 | 65 | Hier eine Beispielabfrage für die Liste aller schweizerischen Bezirke im Kanton *Aargau* (Schlüssel "19"): 66 | 67 | === "Powershell 7" 68 | 69 | ``` powershell 70 | curl -X GET 'https://openplzapi.org/ch/Cantons/19/Districts' -H 'accept: text/json' | ConvertFrom-Json | ConvertTo-Json 71 | ``` 72 | 73 | === "Bash" 74 | 75 | ``` bash 76 | curl -X GET 'https://openplzapi.org/ch/Cantons/19/Districts' -H 'accept: text/json' | json_pp 77 | ``` 78 | 79 | Die meisten Abfragen Verwaltungseinheiten unterliegen einem [Paging](paging.md), d.h. das Resultat wird in adressierbaren Datenblöcken zurückgeliefert. Standardmäßig wird nur der erste Block bzw. die erste Seite mit maximal 50 Einträgen zurückgeliefert. Dies kann aber durch Angabe der optionalen Parameter `page` und `pageSize` beeinflusst werden. 80 | 81 | ### Postleitzahlen und Orte 82 | 83 | Orte können an Hand ihres Namens oder ihrer Postleitzahl gesucht werden. Die Suche kann sehr flexibel mittels regulären Ausdrücken gestaltet werden. Es wird der [POSIX Regular Expressions Syntax](regex.md) unterstützt. 84 | 85 | Hier eine Beispielabfrage für die deutsche Postleitzahl *13156*: 86 | 87 | === "Powershell 7" 88 | 89 | ``` powershell 90 | curl -X GET 'https://openplzapi.org/de/Localities?postalCode=13156' -H 'accept: text/json' | ConvertFrom-Json | ConvertTo-Json 91 | ``` 92 | 93 | === "Bash" 94 | 95 | ``` bash 96 | curl -X GET 'https://openplzapi.org/de/Localities?postalCode=13156' -H 'accept: text/json' | json_pp 97 | ``` 98 | 99 | Hier eine Beispielabfrage für alle deutschen Postleitzahlen, die mit *13* beginnen. Der reguläre Ausruck `^13` ist [URL-kodiert](url-encoding.md): 100 | 101 | === "Powershell 7" 102 | 103 | ``` powershell 104 | curl -X GET 'https://openplzapi.org/de/Localities?postalCode=%5E13' -H 'accept: text/json' | ConvertFrom-Json | ConvertTo-Json 105 | ``` 106 | 107 | === "Bash" 108 | 109 | ``` bash 110 | curl -X GET 'https://openplzapi.org/de/Localities?postalCode=%5E13' -H 'accept: text/json' | json_pp 111 | ``` 112 | 113 | Ortsabfragen unterliegen einem [Paging](paging.md), d.h. das Resultat wird in adressierbaren Datenblöcken zurückgeliefert. Standardmäßig wird nur der erste Block bzw. die erste Seite mit maximal 50 Orte zurückgeliefert. Dies kann aber durch Angabe der optionalen Parameter `page` und `pageSize` beeinflusst werden. 114 | 115 | Hier das erste Beispiel mit explizitem Paging (zweite Seite mit maximal 20 Orte): 116 | 117 | === "Powershell 7" 118 | 119 | ``` powershell 120 | curl -X GET 'https://openplzapi.org/de/Localities?postalCode=13156&page=2&pageSize=20' -H 'accept: text/json' | ConvertFrom-Json | ConvertTo-Json 121 | ``` 122 | 123 | === "Bash" 124 | 125 | ``` bash 126 | curl -X GET 'https://openplzapi.org/de/Localities?postalCode=13156&page=2&pageSize=20' -H 'accept: text/json' | json_pp 127 | ``` 128 | 129 | ### Straßen 130 | 131 | Straßen können an Hand ihres Namens, ihrer Postleitzahl oder ihres Ortsnamens gesucht werden. Die Suche kann sehr flexibel mittels regulären Ausdrücken gestaltet werden. Es wird der [POSIX Regular Expressions Syntax](regex.md) unterstützt. 132 | 133 | Hier eine Beispielabfrage für die deutsche Straße *Grabbeallee* (gibt es nur einmal in Berlin): 134 | 135 | === "Powershell 7" 136 | 137 | ``` powershell 138 | curl -X GET 'https://openplzapi.org/de/Streets?name=Grabbeallee' -H 'accept: text/json' | ConvertFrom-Json | ConvertTo-Json 139 | ``` 140 | 141 | === "Bash" 142 | 143 | ``` bash 144 | curl -X GET 'https://openplzapi.org/de/Streets?name=Grabbeallee' -H 'accept: text/json' | json_pp 145 | ``` 146 | 147 | Hier eine Beispielabfrage für alle Straßen in Berlin, die mit *G* anfängt und mit *allee* aufhört. Der reguläre Ausruck `^G.*allee$` ist [URL-kodiert](url-encoding.md): 148 | 149 | === "Powershell 7" 150 | 151 | ``` powershell 152 | curl -X GET 'https://openplzapi.org/de/Streets?name=%5EG.*allee%24&locality=Berlin' -H 'accept: text/json' | ConvertFrom-Json | ConvertTo-Json 153 | ``` 154 | 155 | === "Bash" 156 | 157 | ``` bash 158 | curl -X GET 'https://openplzapi.org/de/Streets?name=%5EG.*allee%24&locality=Berlin' -H 'accept: text/json' | json_pp 159 | ``` 160 | 161 | Straßenabfragen unterliegen einem [Paging](paging.md), d.h. das Resultat wird in adressierbaren Datenblöcken zurückgeliefert. Standardmäßig wird nur der erste Block bzw. die erste Seite mit maximal 50 Straßen zurückgeliefert. Dies kann aber durch Angabe der optionalen Parameter `page` und `pageSize` beeinflusst werden. 162 | 163 | Hier das erste Beispiel mit explizitem Paging (zweite Seite mit maximal 20 Straßen): 164 | 165 | === "Powershell 7" 166 | 167 | ``` powershell 168 | curl -X GET 'https://openplzapi.org/de/Streets?name=Grabbeallee&page=2&pageSize=20' -H 'accept: text/json' | ConvertFrom-Json | ConvertTo-Json 169 | ``` 170 | 171 | === "Bash" 172 | 173 | ``` bash 174 | curl -X GET 'https://openplzapi.org/de/Streets?name=Grabbeallee&page=2&pageSize=20' -H 'accept: text/json' | json_pp 175 | ``` 176 | 177 | ### Volltextsuche 178 | 179 | Für jedes Land kann eine [Volltextsuche](fulltextsearch.md) über Straßenname, Postleitzahl und Ortsname durchgeführt werden. 180 | 181 | Hier eine Volltextsuche für Deutschland mit dem Suchbegriff `Berlin, Pariser Platz`. Der Suchbegriff ist [URL-kodiert](url-encoding.md): 182 | 183 | === "Powershell 7" 184 | 185 | ``` powershell 186 | curl -X GET 'https://openplzapi.org/de/FullTextSearch?searchTerm=Berlin%2C%20Pariser%20Platz' -H 'accept: text/json' | ConvertFrom-Json | ConvertTo-Json 187 | ``` 188 | 189 | === "Bash" 190 | 191 | ``` bash 192 | curl -X GET 'https://openplzapi.org/de/FullTextSearch?searchTerm=Berlin%2C%20Pariser%20Platz' -H 'accept: text/json' | json_pp 193 | ``` 194 | 195 | Hier eine Volltextsuche für Liechtenstein mit dem Suchbegriff `9490 Alte Landstrasse`. Der Suchbegriff ist [URL-kodiert](url-encoding.md): 196 | 197 | === "Powershell 7" 198 | 199 | ``` powershell 200 | curl -X GET 'https://openplzapi.org/li/FullTextSearch?searchTerm=9490%20Alte%20Landstrasse' -H 'accept: text/json' | ConvertFrom-Json | ConvertTo-Json 201 | ``` 202 | 203 | === "Bash" 204 | 205 | ``` bash 206 | curl -X GET `https://openplzapi.org/li/FullTextSearch?searchTerm=9490%20Alte%20Landstrasse' -H 'accept: text/json' | json_pp 207 | ``` 208 | 209 | Die Volltextsuche unterliegt einem [Paging](paging.md), d.h. das Resultat wird in adressierbaren Datenblöcken zurückgeliefert. Standardmäßig wird nur der erste Block bzw. die erste Seite mit maximal 50 Straßen zurückgeliefert. Dies kann aber durch Angabe der optionalen Parameter `page` und `pageSize` beeinflusst werden. 210 | 211 | ## Tipps und Tricks 212 | 213 | Um die Bildschirmausgabe von `curl` in eine Datei zu schreiben, kann der Parameter `-o` genutzt werden. Das folgende Beispiel speichert alle Kantone der Schweiz in eine JSON-formartierte Textdatei. 214 | 215 | === "Powershell 7" 216 | 217 | ``` powershell 218 | curl -X GET 'https://openplzapi.org/ch/Cantons' -H 'accept: text/json' -o 'cantons.json' 219 | ``` 220 | 221 | === "Bash" 222 | 223 | ``` bash 224 | curl -X GET 'https://openplzapi.org/ch/Cantons' -H 'accept: text/json' -o 'cantons.json' 225 | ``` 226 | -------------------------------------------------------------------------------- /de/docs/libraries.md: -------------------------------------------------------------------------------- 1 | Die OpenPLZ API kann direkt per HTTP-Aufruf konsumiert werden. Schicker ist jedoch, soweit vorhanden, die Nutzung einer Client-Bibliothek. 2 | 3 | Die folgenden Bibliotheken sind verfügbar: 4 | 5 | ## .NET 6 | 7 | - [openpotato/openplzapi-client.net](https://github.com/openpotato/openplzapi-client.net): Offizielle OpenPLZ API [.NET](https://dotnet.microsoft.com/)-Client-Bibliothek. 8 | 9 | ## Python 10 | 11 | - [openpotato/openplzapi-client.py](https://github.com/openpotato/openplzapi-client.py): Offizielle OpenPLZ API [Python](https://www.python.org/)-Client-Bibliothek. 12 | 13 | ## PHP 14 | 15 | - [openpotato/openplzapi-client.php](https://github.com/openpotato/openplzapi-client.php): Offizielle OpenPLZ API [PHP](https://www.php.net/)-Client-Bibliothek. 16 | 17 | ## Delphi 18 | 19 | - [openpotato/openplzapi-client.delphi](https://github.com/openpotato/openplzapi-client.delphi): Offizielle OpenPLZ API [Delphi](https://www.embarcadero.com/products/delphi)-Client-Bibliothek. 20 | -------------------------------------------------------------------------------- /de/docs/liechtenstein.md: -------------------------------------------------------------------------------- 1 | Das OpenPLZ API-Datenverzeichnis für [Liechtenstein](https://de.wikipedia.org/wiki/Liechtenstein) umfasst Straßennamen, Postleitzahlen, Ortsnamen und Verwaltungseinheiten (Gemeinden). 2 | 3 | ## Verwaltungsstruktur 4 | 5 | Die Verwaltungsstruktur Liechtensteins ist klar gegliedert und orientiert sich an der Kleinheit des Staates. Sie besteht aus wenigen, überschaubaren Ebenen, die zentral organisiert sind. 6 | 7 | **Fürstentum** 8 | 9 | : Der Staat Liechtenstein als oberste Verwaltungseinheit und souveräne Instanz. Liechtenstein ist eine konstitutionelle Erbmonarchie auf demokratischer und parlamentarischer Grundlage. Die Staatsführung erfolgt durch den Fürsten und die Regierung. 10 | 11 | **Gemeinden** 12 | 13 | : Die einzige untergeordnete Verwaltungsebene, bestehend aus insgesamt 11 Gemeinden. Gemeinden sind für die lokale Verwaltung zuständig und verfügen über eigene Kompetenzen in Bereichen wie Bauwesen und Infrastruktur. Jede Gemeinde wird durch einen Gemeinderat und einen Vorsteher (Bürgermeister) vertreten. 14 | 15 | **Regionen (historische Einordnung)** 16 | 17 | : Informelle Gruppierungen von Gemeinden, die keine offizielle Verwaltungsebene darstellen. Liechtenstein ist traditionell in zwei historische Regionen – Oberland und Unterland – aufgeteilt, die jedoch keine administrative Bedeutung haben. 18 | 19 | ## Abfrage Gemeinden 20 | 21 | Die 11 liechtensteinischen Gemeinden werden über den folgenden API-Endpunkt abgefragt: 22 | 23 | !!! info "" 24 | 25 | **`openplzapi.org/li/Communes`** 26 | 27 | : Liste aller Gemeinden in Liechtenstein 28 | 29 | Pro Gemeinde werden folgende Attribute geliefert: 30 | 31 | + `key (string)`: Gemeindenummer (4-stellig) 32 | + `name (string)`: Amtlicher Gemeindename 33 | + `electoralDistrict (string)`: Name des Wahlkreises. Mögliche Werte sind: 34 | + `Oberland` 35 | + `Unterland` 36 | 37 | Hier eine Beispielabfrage für die komplette Liste der Gemeinden: 38 | 39 | ``` 40 | GET https://openplzapi.org/li/Communes 41 | ``` 42 | 43 | ## Abfrage Postleitzahlen und Orte 44 | 45 | Die Abfrage der Postleitzahlen und Orte erfolgt über folgenden API-Endpunkt: 46 | 47 | !!! info "" 48 | 49 | **`openplzapi.org/li/Localities?postalCode={Postleitzahl}&name={Ortsname}`** 50 | 51 | : Sucht alle Orte, die zur Postleitzahl und/oder zum Ortsnamen passen. Die Parameter `postalCode` und `name` können zusammen oder jeweils exklusiv genutzt werden. Beide Parameter unterstützen auch [regulären Ausdrücke](regex.md). Die Abfrage unterliegt einem [Paging](paging.md). 52 | 53 | Pro Ort werden folgende Attribute geliefert: 54 | 55 | + `name (string)`: Name des Ortes 56 | + `postalcode (string)`: Postleitzahl des Ortes 57 | + `commune.key (string)`: Gemeindenummer (4-stellig) 58 | + `commune.name (string)`: Amtlicher Gemeindename 59 | 60 | Hier eine Beispielabfrage für die Postleitzahl *9490*: 61 | 62 | ``` 63 | GET https://openplzapi.org/li/Localities?postalCode=9490 64 | ``` 65 | 66 | Hier eine Beispielabfrage für alle deutschen Postleitzahlen, die mit *94* beginnen. Der [reguläre Ausruck](regex.md) `^94` ist [URL-kodiert](url-encoding.md): 67 | 68 | ``` 69 | GET https://openplzapi.org/li/Localities?postalCode=%5E94 70 | ``` 71 | 72 | ## Abfrage Straßen 73 | 74 | Die Abfrage der Straßen erfolgt über folgende API-Endpunkte: 75 | 76 | !!! info "" 77 | 78 | **`openplzapi.org/li/Streets?name={Straßenname}&postalCode={Postleitzahl}&locality={Ortsname}`** 79 | 80 | : Sucht alle Straßen, die zum Straßennamen und/oder der Postleitzahl und/oder zum Ortsnamen passen. Die Parameter `name`, `postalCode` und `locality` können zusammen oder jeweils exklusiv genutzt werden. Alle drei Parameter unterstützen auch [regulären Ausdrücke](regex.md). Die Abfrage unterliegt einem [Paging](paging.md). 81 | 82 | **`openplzapi.org/li/FullTextSearch?searchTerm={Suchbegriff}`** 83 | 84 | : Sucht alle Straßen mittels [Volltextsuche](fulltextsearch.md) über Straßenname, Postleitzahl und Ortsname. Die Abfrage unterliegt einem [Paging](paging.md). 85 | 86 | Pro Straße werden folgende Attribute geliefert: 87 | 88 | + `key (string)`: Straßenschlüssel 89 | + `name (string)`: Name der Straße 90 | + `status (string)`: Straßenstatus. Mögliche Werte sind: 91 | + `Planned` 92 | + `Real` 93 | + `Outdated` 94 | + `postalcode (string)`: Postleitzahl des Ortes 95 | + `locality (string)`: Name des Ortes 96 | + `commune.key (string)`: Gemeindenummer (4-stellig) 97 | + `commune.name (string)`: Amtlicher Gemeindename 98 | 99 | Hier eine Beispielabfrage für die Straße *Alte Landstrasse*: 100 | 101 | ``` 102 | GET https://openplzapi.org/li/Streets?name=Alte%20Landstrasse 103 | ``` 104 | 105 | Hier eine Beispielabfrage für alle Straßen in Vaduz, die mit *Alte* anfangen und mit *strasse* aufhören. Der [reguläre Ausruck](regex.md) `^Alte.*strasse$` ist [URL-kodiert](url-encoding.md): 106 | 107 | ``` 108 | GET https://openplzapi.org/li/Streets?name=%5EAlte.%2Astrasse%24&locality=Vaduz 109 | ``` 110 | 111 | Hier eine Volltextsuche mit dem Suchbegriff `Vaduz Alte Landstrasse`. Der Suchbegriff ist [URL-kodiert](url-encoding.md): 112 | 113 | ``` 114 | GET https://openplzapi.org/li/FullTextSearch?searchTerm=Vaduz%20Alte%20Landstrasse 115 | ``` -------------------------------------------------------------------------------- /de/docs/paging.md: -------------------------------------------------------------------------------- 1 | # Paging 2 | 3 | Die meisten API-Endpunkte im OpenPLZ API-Projekt implementieren das sogenannte **Paging**. 4 | 5 | ## Was ist Paging? 6 | 7 | Paging in Web-Diensten ist eine Technik, um die Ergebnisse großer Datenmengen in kleinere, handhabbare Teile zu unterteilen. Anstatt alle Ergebnisse einer Abfrage auf einmal zu senden, wird der Inhalt in Seiten (pages) aufgeteilt, sodass ein Client sequentiell oder nach Bedarf auf verschiedene Seiten zugreifen kann. 8 | 9 | ## Warum Paging? 10 | 11 | Beginnen wir mit einem Beispiel. Die folgende Abfrage: 12 | 13 | ``` 14 | GET https://openplzapi.org/de/Streets?locality=Berlin 15 | ``` 16 | 17 | würde ohne Paging 15335 Straßen zurückliefern. Das ist eine ganze Menge und würde den Server unverhältnismäßig belasten, die Netzwerklatenz erhöhen und die Antwortzeiten verlängern. Besser ist es, diese Daten häppchenweise, in sogenannten Seiten (pages) zu übertagen. Wie groß das Häppchen, also die Seite sein soll, kannst Du beim Aufruf konfigurieren. 18 | 19 | ## Wie genau funktioniert Paging? 20 | 21 | Paging wird durch spezielle URL-Parametern im API-Aufruf konfiguriert. Damit wird angegeben, welche Seite von Ergebnissen der Client sehen möchte und wie viele Ergebnisse pro Seite angezeigt werden sollen. Die URL-Parameter heißen: 22 | 23 | + `page`: Der Index der Seite, die angefordert wird. 24 | + `pageSize`: Die Anzahl der Elemente pro Seite. 25 | 26 | Dieser Aufruf liefert die ersten 10 Adressen für Berlin zurück: 27 | 28 | ``` 29 | GET https://openplzapi.org/de/Streets?locality=Berlin&page=1&pageSize=10 30 | ``` 31 | 32 | Der nächste Aufruf liefert die folgenden 10 Adressen für Berlin zurück: 33 | 34 | ``` 35 | GET https://openplzapi.org/de/Streets?locality=Berlin&page=2&pageSize=10 36 | ``` 37 | 38 | Wird der URL-Parameter `page` beim Aufruf weggelassen, gilt der Standardwert `page=1`. Wird der URL-Parameter `pageSize` beim Aufruf weggelassen, gilt der Standardwert `pageSize=50`. Der Aufruf 39 | 40 | ``` 41 | GET https://openplzapi.org/de/Streets?locality=Berlin 42 | ``` 43 | 44 | entspricht also dem Aufruf 45 | 46 | ``` 47 | GET https://openplzapi.org/de/Streets?locality=Berlin&page=1&pageSize=50 48 | ``` 49 | 50 | Die Maximalgröße für eine Seite ist 50. 51 | 52 | ## Woher weiß ich, wieviel Pages es gibt? 53 | 54 | Bei einer erfolgreichen Antwort eines API-Aufrufs werden in den [HTTP-Response-Headers](https://developer.mozilla.org/docs/Web/HTTP/Headers) zusätzliche Informationen mitgeliefert. Schauen wir uns eine typische Response-Header-Liste an: 55 | 56 | ``` 57 | content-security-policy: default-src https: data: 'unsafe-inline' 58 | content-type: text/json; charset=utf-8 59 | date: Thu,26 Sep 2024 09:26:48 GMT 60 | permissions-policy: accelerometer=(),camera=(),geolocation=(),gyroscope=(),magnetometer=(),microphone=(),payment=(),usb=(),interest-cohort=() 61 | referrer-policy: strict-origin-when-cross-origin 62 | server: nginx 63 | strict-transport-security: max-age=2592000 64 | x-content-type-options: nosniff 65 | x-frame-options: SAMEORIGIN 66 | x-page: 1 67 | x-page-size: 10 68 | x-total-count: 15335 69 | x-total-pages: 1534 70 | ``` 71 | 72 | Interessant sind für uns hier die letzten vier Werte: 73 | 74 | + `x-page`: Der Index der Seite, die angefordert wurde. 75 | + `x-page-size`: Die Anzahl der Elemente pro Seite. 76 | + `x-total-count`: Die Gesamtzahl der Elemente für diese Anfrage. 77 | + `x-total-pages`: Die Anzahl der Seiten für diese Anfrage. 78 | 79 | Diese Werte werden bei allen API-Endpunkten, die Paging implementieren zurückgeliefert. 80 | 81 | !!! note "Warum nicht im JSON-Payload?" 82 | 83 | Die OpenPLZ API liefert die Paging-Metadaten in den HTTP-Response-Headers zurück. Es gibt andere Implementationen, die liefern diese Information als Teil des JSON-Payloads, welcher die eigentliche Antwort repräsentiert, zurück. Wir haben uns dagegen entscheiden, weil wir nicht nur JSON sondern auch CSV als Payload-Format unterstützen. 84 | 85 | ## API-Endpunkte ohne Paging 86 | 87 | Einige API-Endpunkte implementieren kein Paging, da die resultierende Datenmenge überschaubar ist: 88 | 89 | + `https://openplzapi.org/at/FederalProvinces` 90 | + `https://openplzapi.org/ch/Cantons` 91 | + `https://openplzapi.org/de/FederalStates` 92 | + `https://openplzapi.org/li/Communes` 93 | 94 | -------------------------------------------------------------------------------- /de/docs/regex.md: -------------------------------------------------------------------------------- 1 | # Reguläre Ausdrücke 2 | 3 | In der OpenPLZ API können Sucheingaben zu Straßennamen, Postleitzahlen oder Ortsnamen optional durch **reguläre Ausdrücke** definiert werden. Die OpenPLZ API unterstützt POSIX-Basisreguläre Ausdrücke (BRE). 4 | 5 | ## Was sind reguläre Ausdrücke? 6 | 7 | Reguläre Ausdrücke (englisch: Regular Expressions, oft abgekürzt als Regex) sind ein Werkzeug zur Textsuche. Sie ermöglichen es, bestimmte Muster in Zeichenketten zu suchen und zu finden. Mit regulären Ausdrücken können komplexe Suchoperationen durchgeführt werden, indem man festlegt, welche Art von Zeichen oder Textstrukturen gesucht werden sollen. 8 | 9 | ## POSIX-Basisreguläre Ausdrücke 10 | 11 | [POSIX-Basisreguläre Ausdrücke (BRE)](https://pubs.opengroup.org/onlinepubs/9799919799/) sind die traditionellere Form von regulären Ausdrücken, die in Unix-ähnlichen Betriebssystemen verwendet werden. Sie bieten eine robuste und effiziente Möglichkeit, Zeichenfolgen zu durchsuchen, abzugleichen und zu manipulieren. Im Gegensatz zu erweiterten regulären Ausdrücken (ERE) müssen viele Sonderzeichen in BRE mit einem Rückwärtsschrägstrich (`\`) maskiert werden, um ihre speziellen Bedeutungen anzunehmen. Dies führt zu einigen syntaktischen Unterschieden zwischen BRE und anderen Formen regulärer Ausdrücke. 12 | 13 | Die BRE-Syntax ist relativ minimalistisch, mit mehreren Metazeichen und Konstrukten zur Definition von Übereinstimmungsregeln. Im Folgenden werden die grundlegenden Komponenten der BRE-Syntax behandelt. 14 | 15 | ### Literale Zeichen 16 | 17 | Ein literales Zeichen ist einfach ein Zeichen, das sich selbst entspricht. Die meisten Zeichen werden als literale Zeichen behandelt, es sei denn, sie sind Metazeichen (z. B. `*`, `.`, `^`), die spezielle Bedeutungen haben. Um ein literales Metazeichen zu finden, musst Du es mit einem Rückwärtsschrägstrich (`\`) maskieren. 18 | 19 | Beispiel: 20 | 21 | + `abc` stimmt genau mit der Zeichenfolge "abc" überein. 22 | 23 | ### Metazeichen und Sonderzeichen in BRE 24 | 25 |

Startanker einer Zeile

26 | 27 | Das Caret-Symbol `^` wird verwendet, um den Anfang einer Zeile oder Zeichenfolge abzugleichen. 28 | 29 | Beispiel: 30 | 31 | + `^abc` stimmt nur mit "abc" überein, wenn es am Anfang einer Zeile steht. 32 | 33 |

Ende einer Zeile

34 | 35 | Das Dollarzeichen `$` stimmt mit dem Ende einer Zeile oder Zeichenfolge überein. 36 | 37 | Beispiel: 38 | 39 | + `abc$` stimmt nur mit "abc" überein, wenn es am Ende einer Zeile steht. 40 | 41 |

Übereinstimmung mit einem beliebigen Zeichen

42 | 43 | Der Punkt `.` wird verwendet, um mit einem beliebigen Zeichen außer dem Zeilenumbruch übereinzustimmen. 44 | 45 | Beispiel: 46 | 47 | + `a.c` stimmt mit jeder dreistelligen Zeichenfolge überein, die mit "a" beginnt und mit "c" endet, wobei jedes beliebige Zeichen dazwischen liegt (z. B. "abc", "a5c"). 48 | 49 |

0 oder mehr Wiederholungen

50 | 51 | Das Sternchen `*` stimmt mit dem vorherigen Element 0 oder mehrmals überein. 52 | 53 | Beispiel: 54 | 55 | + `ab*c` stimmt mit "ac", "abc", "abbc", "abbbc" usw. überein. 56 | 57 |

Übereinstimmung mit einem Zeichen aus einer Menge

58 | 59 | Mit Klammerausdrücken `[]` (auch als Zeichenklassen bekannt) kann eine Reihe von Zeichen definiert werden, die auf eine bestimmte Position in einer Zeichenkette passen sollen. 60 | 61 | Beispiele: 62 | 63 | + `[abc]` stimmt mit "a", "b" oder "c" überein. 64 | + `[0-9]` stimmt mit jeder Ziffer zwischen 0 und 9 überein. 65 | 66 | Sonderfälle bei Klammerausdrücken: 67 | 68 | + Ein Caret (`^`) am Anfang eines Klammerausdrucks negiert die Zeichenauswahl, was bedeutet, dass es mit jedem Zeichen außer den aufgelisteten übereinstimmt. 69 | 70 | Beispiel: 71 | 72 | + `[^abc]` stimmt mit jedem Zeichen außer "a", "b" oder "c" überein. 73 | 74 | + Ein Bindestrich (`-`) kann verwendet werden, um einen Zeichenbereich anzugeben. 75 | 76 | Beispiel: 77 | 78 | + `[a-z]` stimmt mit jedem Kleinbuchstaben überein. 79 | 80 |

Maskierungszeichen

81 | 82 | In BRE verlieren Metazeichen wie `*`, `.`, `^` und `$` ihre speziellen Bedeutungen, wenn sie mit einem Rückwärtsschrägstrich `\` maskiert werden. 83 | 84 | Beispiele: 85 | 86 | + `\*` stimmt mit einem literalen Sternchen überein. 87 | + `\\` stimmt mit einem literalen Rückwärtsschrägstrich überein. 88 | 89 | ### Wiederholungsoperatoren 90 | 91 |

Genau `m` Vorkommen übereinstimmen

92 | 93 | `\{m\}` stimmt mit genau `m` Vorkommen des vorherigen Elements überein. 94 | 95 | Beispiel: 96 | 97 | + `a\{3\}` stimmt genau mit drei Vorkommen von "a" überein (d. h. "aaa"). 98 | 99 |

Zwischen `m` und `n` Vorkommen übereinstimmen

100 | 101 | `\{m,n\}` stimmt mit zwischen `m` und `n` Vorkommen des vorherigen Elements überein. 102 | 103 | Beispiel: 104 | 105 | + `a\{2,4\}` stimmt mit zwischen zwei und vier Vorkommen von "a" überein (d. h. "aa", "aaa" oder "aaaa"). 106 | 107 |

Mindestens `m` Vorkommen übereinstimmen

108 | 109 | `\{m,\}` stimmt mit `m` oder mehr Vorkommen des vorherigen Elements überein. 110 | 111 | Beispiel: 112 | 113 | + `a\{2,\}` stimmt mit mindestens zwei Vorkommen von "a" überein (d. h. "aa", "aaa", "aaaa" usw.). 114 | 115 | ### Gruppierung und Rückverweise 116 | 117 |

Gruppierung

118 | 119 | Klammern `\(` und `\)` werden verwendet, um Teile des Musters zu gruppieren. Der gruppierte Teil des Musters wird als einzelnes Element behandelt. 120 | 121 | Beispiel: 122 | 123 | + `\(ab\)*` stimmt mit 0 oder mehr Vorkommen von "ab" überein. 124 | 125 |

Rückverweis

126 | 127 | Ein Rückverweis bezieht sich auf einen zuvor gruppierten Unterausdruck. In BRE werden Rückverweise durch `\n` dargestellt, wobei `n` eine Zahl ist, die die `n`-te Gruppe im Muster repräsentiert. Der Rückverweis stimmt mit dem gleichen Text wie die entsprechende Gruppe überein. 128 | 129 | Beispiel: 130 | 131 | + `\(abc\)\1` stimmt mit "abcabc" überein, da sich `\1` auf den ersten gruppierten Ausdruck "abc" bezieht. 132 | 133 | ### Anker 134 | 135 | Anker in BRE werden verwendet, um Positionen und nicht Zeichen abzugleichen. 136 | 137 | + `^`: Stimmt mit dem Anfang einer Zeile überein. 138 | + `$`: Stimmt mit dem Ende einer Zeile überein. 139 | 140 | ### Maskierte Metazeichen 141 | 142 | Einige der Metazeichen in BRE müssen maskiert werden, was sich von anderen regulären Ausdrucks-Syntaxen unterscheidet. Zum Beispiel: 143 | 144 | + `\{` und `\}` müssen maskiert werden, um Wiederholungen darzustellen. 145 | + Klammern `\(` und `\)` werden zur Gruppierung verwendet. 146 | 147 | ### Beispiele 148 | 149 | Hier sind einige Beispiele, um zu demonstrieren, wie BRE in der Praxis funktioniert: 150 | 151 |

Datumsformat

152 | 153 | Muster: `\([0-9]\{2\}\)\([0-9]\{2\}\)\([0-9]\{4\}\)` 154 | 155 | Dieses Muster stimmt mit einem Datumsformat überein, bei dem: 156 | 157 | + Die ersten beiden Ziffern den Tag darstellen. 158 | + Die zweiten beiden Ziffern den Monat darstellen. 159 | + Die letzten vier Ziffern das Jahr darstellen. 160 | 161 | Beispiel für eine Übereinstimmung: "25092024" (steht für 25. September 2024). 162 | 163 |

Telefonnummer

164 | 165 | Muster: `\([0-9]\{3\}\)-[0-9]\{3\}-[0-9]\{4\}` 166 | 167 | Dieses Muster stimmt mit einer Telefonnummer im Format `XXX-XXX-XXXX` überein, wobei `X` eine Ziffer darstellt. 168 | 169 | Beispiel für eine Übereinstimmung: "123-456-7890". 170 | 171 |

Wiederholte Wörter

172 | 173 | Muster: `\(Wort\)\1` 174 | 175 | Dieses Muster stimmt mit dem Wort "Wort" überein, das zweimal hintereinander wiederholt wird, z. B. "WortWort". 176 | -------------------------------------------------------------------------------- /de/docs/sources.md: -------------------------------------------------------------------------------- 1 | Die Datengrundlage für **OpenPLZ API** basiert komplett auf öffentlichen Quellen der Länder sowie auf Daten des [OpenStreetMap-Projekts](https://www.openstreetmap.de/). Im folgenden werden die Quellen im Detail aufgeführt. 2 | 3 | ## Deutschland 4 | 5 | ### Gemeindeverzeichnis 6 | 7 | Das [Statistische Bundesamt (Destatis)](https://www.destatis.de) stellt die *Gemeindeleitdatei GV100* zum Download bereit. Diese Datei enthält Informationen zu allen Regionaleinheiten Deutschlands (Bundesländer, Regierungsbezirke, Kreise, Gemeindeverbände und Gemeinden). Die Gemeindeleitdatei GV100 ist eine Textdatei mit einer festen Satzstruktur von 220 Stellen, die regelmäßig aktualisiert wird. 8 | 9 | Quelle: 10 | 11 | + [Gemeindeverzeichnis-Informationssystem GV-ISys](https://www.destatis.de/DE/Themen/Laender-Regionen/Regionales/Gemeindeverzeichnis/_inhalt.html) 12 | 13 | ### Straßenverzeichnis 14 | 15 | In Deutschland gibt es keine frei zugängliche Datenbank, um alle Postleitzahlen und/oder Straßennamen Deutschlands zu erhalten. Es gibt zwar kommerzielle Dienste, die derartige Daten anbieten, aber diese kosten Geld und dürfen nicht im Sinne von Open Data verwendet werden. 16 | 17 | Als Alternative bietet sich das gemeinschaftlich betriebene [OpenStreetMap-Projekt](https://www.openstreetmap.org/) an. Jede Woche wird eine neue und vollständige Kopie aller Daten in OpenStreetMap sowohl als komprimierte XML-Datei als auch im [PBF-Format (Protocolbuffer Binary Format)](https://wiki.openstreetmap.org/wiki/PBF_Format) zur Verfügung gestellt. Alle Infos dazu finden sich unter [Planet OSM](https://planet.openstreetmap.org). Die Datenbankdatei ist sehr groß, daher arbeitet OpenPLZ API mit einem regionalen Auszug für Deutschland. Die Straßen werden mit allen relevanten Informationen aus den OpenStreetMap-Daten extrahiert und mit den Daten aus dem GV-ISys verknüpft. Das Ergebnis ist eine CSV-Datei, die ihren Platz [im folgenden GitHub-Repo](https://github.com/openpotato/openplzapi.data) bekommen hat und regelmäßig aktualisiert wird. 18 | 19 | Quelle: 20 | 21 | + [OpenStreetMap-Daten für Deutschland](https://download.geofabrik.de/europe/germany.html) 22 | 23 | ## Österreich 24 | 25 | ### Gemeindeverzeichnis 26 | 27 | Die [Bundesanstalt Statistik Österreich (STATISTIK AUSTRIA)](https://www.statistik.at/) stellt Downloads zur regionalen Gliederung bereit. 28 | 29 | Quellen: 30 | 31 | + [Statistik Austria Open.data](https://data.statistik.gv.at/) 32 | + [Politische Bezirke und Bundesländer (PDF)](https://www.statistik.at/verzeichnis/reglisten/polbezirke.pdf) 33 | + [Gemeinden (PDF)](https://www.statistik.at/verzeichnis/reglisten/gemliste_knz.pdf) 34 | 35 | ### Straßenverzeichnis 36 | 37 | Die [Bundesanstalt Statistik Österreich (STATISTIK AUSTRIA)](https://www.statistik.at/) stellt auch das komplette, wöchentlich aktualisierte Straßenverzeichnis bereit. 38 | 39 | Quelle: 40 | 41 | + [Straßenverzeichnis](https://www.statistik.at/statistik.at/strassen) 42 | 43 | ## Schweiz 44 | 45 | ### Gemeindeverzeichnis 46 | 47 | Das [Bundesamt für Statistik](https://www.bfs.admin.ch) stellt APIs und Downloads zur regionalen Gliederung bereit. 48 | 49 | Quelle: 50 | 51 | + [Applikation der Schweizer Gemeinden](https://www.agvchapp.bfs.admin.ch/de) 52 | 53 | ### Straßenverzeichnis 54 | 55 | Das [Bundesamt für Landestopografie](https://www.swisstopo.admin.ch/de/home.html) stellt das komplette, regelmäßig aktualisierte Straßenverzeichnis bereit. 56 | 57 | Quelle: 58 | 59 | + [Straßenverzeichnis](https://www.swisstopo.admin.ch/de/geodata/amtliche-verzeichnisse/strassenverzeichnis.html) 60 | 61 | ## Liechtenstein 62 | 63 | ### Gemeindeverzeichnis 64 | 65 | Die Liste der Gemeinden ergibt sich aus dem Liechtensteiner Gemeindegesetz vom 20. März 1996. 66 | 67 | Quellen: 68 | 69 | + [Gemeindegesetz (GemG)](https://www.gesetze.li/konso/1996076000) 70 | + [Wikipedia: Verwaltungsgliederung Liechtensteins](https://w.wiki/BEPn) 71 | 72 | ### Straßenverzeichnis 73 | 74 | Das [Schweizer Bundesamt für Landestopografie](https://www.swisstopo.admin.ch/de/home.html) stellt das komplette, regelmäßig aktualisierte Straßenverzeichnis auch für Liechtenstein bereit. 75 | 76 | Quelle: 77 | 78 | + [Straßenverzeichnis](https://www.swisstopo.admin.ch/de/geodata/amtliche-verzeichnisse/strassenverzeichnis.html) 79 | -------------------------------------------------------------------------------- /de/docs/switzerland.md: -------------------------------------------------------------------------------- 1 | Das OpenPLZ API-Datenverzeichnis für die [Schweiz](https://de.wikipedia.org/wiki/Schweiz) umfasst Straßennamen, Postleitzahlen, Ortsnamen und Verwaltungseinheiten (Gemeinden, Bezirke und Kantone). 2 | 3 | ## Verwaltungstruktur 4 | 5 | Die Verwaltungsstruktur der Schweiz basiert auf einem stark ausgeprägten Föderalismus. Sie ist in drei Ebenen unterteilt, die jeweils eigene Kompetenzen und Verantwortungsbereiche besitzen. 6 | 7 | **Bund** 8 | 9 | : Die oberste Verwaltungseinheit des Schweizer Bundesstaates. Der Bund ist für übergeordnete Aufgaben wie Außenpolitik, Landesverteidigung und die schweizerische Rechtsordnung zuständig. Die Legislative wird durch die Bundesversammlung (Nationalrat und Ständerat) gebildet, die Exekutive durch den Bundesrat. 10 | 11 | **Kantone** 12 | 13 | : Die föderalen Einheiten unterhalb des Bundes, bestehend aus 26 Kantonen (20 Vollkantone und 6 Halbkantone). Jeder Kanton besitzt eine eigene Verfassung, eine Regierung, ein Parlament und Gerichte. Die Kantone haben weitreichende Autonomie, insbesondere in den Bereichen Bildung, Gesundheitswesen und Polizei. 14 | 15 | **Gemeinden** 16 | 17 | : Die kleinste Verwaltungseinheit mit umfassenden Selbstverwaltungsrechten. Es gibt rund 2.000 Gemeinden in der Schweiz, wobei die Anzahl durch Fusionen kontinuierlich abnimmt. Gemeinden sind für lokale Angelegenheiten wie die Raumplanung, Schulwesen und Wasserversorgung verantwortlich. Sie besitzen eigene Behörden, meist bestehend aus einem Gemeinderat und einer Gemeindeverwaltung. 18 | 19 | ## Abfrage Kantone 20 | 21 | Die 26 Schweizer Kantone werden über den folgenden API-Endpunkt abgefragt: 22 | 23 | !!! info "" 24 | 25 | **`openplzapi.org/ch/Cantons`** 26 | 27 | : Liste aller Kantone in der Schweiz 28 | 29 | Pro Kanton werden folgende Attribute geliefert: 30 | 31 | + `key (string)`: Bfs-Nummer des Kantons (max. 2-stellig) 32 | + `historicalCode (string)`: Historisierte Nummer des Kantons 33 | + `name (string)`: Kantonsname 34 | + `shortName (string)`: Kantonskürzel (2-stellig) 35 | 36 | Hier eine Beispielabfrage für die komplette Liste der Kantone: 37 | 38 | ``` 39 | GET https://openplzapi.org/ch/Cantons 40 | ``` 41 | 42 | ## Abfrage Bezirke 43 | 44 | Die Abfrage der Bezirke erfolgt über folgenden API-Endpunkt: 45 | 46 | !!! info "" 47 | 48 | **`openplzapi.org/at/Cantons/{Kantonsnummer}/Districts`** 49 | 50 | : Liste aller Bezirke in einem Kanton. Als Parameter wird die Kantonsnummer (2-stellig) benötigt. Die Abfrage unterliegt einem [Paging](paging.md). 51 | 52 | Pro Bezirk werden folgende Attribute geliefert: 53 | 54 | + `key (string)`: Bfs-Nummer des Bezirks (max. 4-stellig) 55 | + `historicalCode (string)`: Historisierte Nummer des Bezirks 56 | + `name (string)`: Bezirksname 57 | + `shortName (string)`: Bezirksname, kurz 58 | + `canton.key (string)`: Bfs-Nummer des Kantons (max. 2-stellig) 59 | + `canton.name (string)`: Kantonsname 60 | + `canton.shortName (string)`: Kantonskürzel (2-stellig) 61 | 62 | Hier eine Beispielabfrage für die Liste der Bezirke im Kanton Freiburg (Kantonsnummer: `10`): 63 | 64 | ``` 65 | GET https://openplzapi.org/ch/Cantons/10/Districts 66 | ``` 67 | 68 | ## Abfrage Gemeinden 69 | 70 | Die Abfrage der Gemeinden erfolgt über folgende API-Endpunkte: 71 | 72 | !!! info "" 73 | 74 | **`openplzapi.org/ch/Cantons/{Bundeslandkennziffer}/Communes`** 75 | 76 | : Liste aller Gemeinden in einem Kanton. Als Parameter wird die Kantonsnummer (1-stellig) benötigt. Die Abfrage unterliegt einem [Paging](paging.md). 77 | 78 | **`openplzapi.org/ch/Districts/{Bezirksschlüssel}/Communes`** 79 | 80 | : Liste aller Gemeinden in einem Bezirk. Als Parameter wird die Bezirksnummer (3-stellig) benötigt. Die Abfrage unterliegt einem [Paging](paging.md). 81 | 82 | Pro Gemeinde werden folgende Attribute geliefert: 83 | 84 | + `key (string)`: Bfs-Nummer der Gemeinde (max. 4-stellig) 85 | + `historicalCode (string)`: Historisierte Nummer der Gemeinde 86 | + `name (string)`: Amtlicher Gemeindename 87 | + `shortName (string)`: Gemeindename, kurz 88 | + `district.key (string)`: Bfs-Nummer des Bezirks (max. 4-stellig) 89 | + `district.name (string)`: Bezirksname 90 | + `district.shortName (string)`: Bezirksname, kurz 91 | + `canton.key (string)`: Bfs-Nummer des Kantons (max. 2-stellig) 92 | + `canton.name (string)`: Kantonsname 93 | + `canton.shortName (string)`: Kantonskürzel (2-stellig) 94 | 95 | Hier eine Beispielabfrage für die Liste der Gemeinden im Kanton Freiburg (Kantonsnummer: `10`): 96 | 97 | ``` 98 | GET https://openplzapi.org/ch/Cantons/10/Communes 99 | ``` 100 | 101 | ## Abfrage Postleitzahlen und Orte 102 | 103 | Die Abfrage der Postleitzahlen und Orte erfolgt über folgende API-Endpunkte: 104 | 105 | !!! info "" 106 | 107 | **`openplzapi.org/ch/Cantons/{Kantonsnummer}/Localities`** 108 | 109 | : Liste aller Orte in einem Kanton. Als Parameter wird die Kantonsnummer (1-stellig) benötigt. Die Abfrage unterliegt einem [Paging](paging.md). 110 | 111 | **`openplzapi.org/ch/Districts/{Bezirksnummer}/Localities`** 112 | 113 | : Liste aller Orte in einen Bezirk. Als Parameter wird die Bezirksnummer (beide 3-stellig) benötigt. Die Abfrage unterliegt einem [Paging](paging.md). 114 | 115 | **`openplzapi.org/ch/Localities?postalCode={Postleitzahl}&name={Ortsname}`** 116 | 117 | : Sucht alle Orte, die zur Postleitzahl und/oder zum Ortsnamen passen. Die Parameter `postalCode` und `name` können zusammen oder jeweils exklusiv genutzt werden. Beide Parameter unterstützen auch [regulären Ausdrücke](regex.md). Die Abfrage unterliegt einem [Paging](paging.md). 118 | 119 | Pro Ort werden folgende Attribute geliefert: 120 | 121 | + `key (string)`: Ortschaftskennziffer 122 | + `name (string)`: Name des Ortes 123 | + `postalcode (string)`: Postleitzahl des Ortes 124 | + `commune.key (string)`: Bfs-Nummer der Gemeinde (max. 4-stellig) 125 | + `commune.name (string)`: Amtlicher Gemeindename 126 | + `commune.shortName (string)`: Gemeindename, kurz 127 | + `district.key (string)`: Bfs-Nummer des Bezirks (max. 4-stellig) 128 | + `district.name (string)`: Bezirksname 129 | + `district.shortName (string)`: Bezirksname, kurz 130 | + `canton.key (string)`: Bfs-Nummer des Kantons (max. 2-stellig) 131 | + `canton.name (string)`: Kantonsname 132 | + `canton.shortName (string)`: Kantonskürzel (2-stellig) 133 | 134 | Hier eine Beispielabfrage für die Postleitzahl *8001*: 135 | 136 | ``` 137 | GET https://openplzapi.org/ch/Localities?postalCode=8001 138 | ``` 139 | 140 | Hier eine Beispielabfrage für alle Schweizer Postleitzahlen, die mit *80* beginnen. Der [reguläre Ausruck](regex.md) `^80` ist [URL-kodiert](url-encoding.md): 141 | 142 | ``` 143 | GET https://openplzapi.org/ch/Localities?postalCode=%5E80 144 | ``` 145 | 146 | ## Abfrage Straßen 147 | 148 | Die Abfrage der Straßen erfolgt über folgende API-Endpunkte: 149 | 150 | !!! info "" 151 | 152 | **`openplzapi.org/ch/Streets?name={Straßenname}&postalCode={Postleitzahl}&locality={Ortsname}`** 153 | 154 | : Sucht alle Straßen, die zum Straßennamen und/oder der Postleitzahl und/oder zum Ortsnamen passen. Die Parameter `name`, `postalCode` und `locality` können zusammen oder jeweils exklusiv genutzt werden. Alle drei Parameter unterstützen auch [regulären Ausdrücke](regex.md). Die Abfrage unterliegt einem [Paging](paging.md). 155 | 156 | **`openplzapi.org/ch/FullTextSearch?searchTerm={Suchbegriff}`** 157 | 158 | : Sucht alle Straßen mittels [Volltextsuche](fulltextsearch.md) über Straßenname, Postleitzahl und Ortsname. Die Abfrage unterliegt einem [Paging](paging.md). 159 | 160 | Pro Straße werden folgende Attribute geliefert: 161 | 162 | + `key (string)`: Straßenschlüssel 163 | + `name (string)`: Name der Straße 164 | + `status (string)`: Straßenstatus. Mögliche Werte sind: 165 | + `Planned` 166 | + `Real` 167 | + `Outdated` 168 | + `postalcode (string)`: Postleitzahl des Ortes 169 | + `locality (string)`: Name des Ortes 170 | + `commune.key (string)`: Bfs-Nummer der Gemeinde (max. 4-stellig) 171 | + `commune.name (string)`: Amtlicher Gemeindename 172 | + `commune.shortName (string)`: Gemeindename, kurz 173 | + `district.key (string)`: Bfs-Nummer des Bezirks (max. 4-stellig) 174 | + `district.name (string)`: Bezirksname 175 | + `district.shortName (string)`: Bezirksname, kurz 176 | + `canton.key (string)`: Bfs-Nummer des Kantons (max. 2-stellig) 177 | + `canton.name (string)`: Kantonsname 178 | + `canton.shortName (string)`: Kantonskürzel (2-stellig) 179 | 180 | Hier eine Beispielabfrage für die Straße *Bederstrasse* (gibt es nur einmal in Zürich): 181 | 182 | ``` 183 | GET https://openplzapi.org/ch/Streets?name=Bederstrasse 184 | ``` 185 | 186 | Hier eine Beispielabfrage für alle Straßen in Zürich, die mit *B* anfangen und mit *strasse* aufhören. Der [reguläre Ausruck](regex.md) `^B.*strasse$` ist [URL-kodiert](url-encoding.md): 187 | 188 | ``` 189 | GET https://openplzapi.org/ch/Streets?name=%5EB.*strasse%24&locality=Z%C3%BCrich 190 | ``` 191 | 192 | Hier eine Volltextsuche mit dem Suchbegriff `Zürich Bederstrasse`. Der Suchbegriff ist [URL-kodiert](url-encoding.md): 193 | 194 | ``` 195 | GET https://openplzapi.org/ch/FullTextSearch?searchTerm=Z%C3%BCrich%20Bederstrasse 196 | ``` -------------------------------------------------------------------------------- /de/docs/url-encoding.md: -------------------------------------------------------------------------------- 1 | # URL-Kodierung 2 | 3 | URLs dürfen nur eine begrenzte Menge an Zeichen enthalten, die in [RFC 3986](https://datatracker.ietf.org/doc/html/rfc3986) definiert sind. Sonderzeichen oder Nicht-ASCII-Zeichen (z.B. deutsche Umlaute) müssen kodiert werden, um Konflikte oder Missverständnisse zu vermeiden. 4 | 5 | ## Was ist URL-Kodierung? 6 | 7 | URL-Kodierung ist ein Verfahren, um spezielle Zeichen in einer URL in ein sicheres Format zu konvertieren. Das ist wichtig, weil URLs nur bestimmte Zeichen enthalten dürfen, wie Buchstaben (`A-Z`, `a-z`), Zahlen (`0-9`) und einige Symbole (`-`, `_`, `.`). 8 | 9 | Zeichen, die diese Regel nicht erfüllen, wie Leerzeichen, `#` oder nicht-englische Buchstaben (`ä`, `ë`, `à`), müssen kodiert werden. Andere Zeichen (z.B. `/`, `?`, `&`) haben eine feste Bedeutung für URLs und dürfen nur kodiert als Parameterwerte in einer Abfrage genutzt werden. 10 | 11 | Bei der Kodierung wird jedes Zeichen durch eine Kombination ersetzt aus: 12 | 13 | 1. Einem **Prozentzeichen (`%`)**. 14 | 2. Zwei **hexadezimalen Ziffern**, die den ASCII- oder UTF-8-Wert des Zeichens darstellen. 15 | 16 | Im Kontext von OpenPLZ API betrifft dies vor allem die Werte und [regulären Ausdrücke](regex.md) in den URL-Parametern `searchTerm`, `name`, `postalCode` und `locality`. 17 | 18 | ## Welche Zeichen müssen kodiert werden? 19 | 20 | 1. Sonderzeichen und Leerzeichen: 21 | 22 | + Ein Leerzeichen wird zu `%20`. 23 | + `&` wird zu `%26`. 24 | + `=` wird zu `%3D`. 25 | + etc. 26 | 27 | 2. Nicht-englische Buchstaben (Umlaute, Akzente usw.): 28 | 29 | + `ä` wird zu `%C3%A4`. 30 | + `ö` wird zu `%C3%B6`. 31 | + `à` wird zu `%C3%A0`. 32 | + `ë` wird zu `%C3%AB`. 33 | + etc. 34 | 35 | 3. Andere spezielle Symbole: 36 | 37 | + `#` wird zu `%23`. 38 | + `+` wird zu `%2B`. 39 | + `/` wird zu `%2F`. 40 | + etc. 41 | 42 | !!! note "Leerzeichen" 43 | 44 | Statt mit `%20` kann ein Leerzeichen auch durch ein Pluszeichen (`+`) repräsentiert werden. 45 | 46 | ## Beispiel 47 | 48 | Das folgende OpenPLZ API-Beispiel liefert alle Straßen für `München` zurück, deren Postleitzahl mit `808` beginnt: 49 | 50 | + Im Orginal: 51 | 52 | ``` 53 | GET https://openplzapi.org/de/Streets?postalcode=^808&locality=München 54 | ``` 55 | 56 | + Mit URL-Kodierung: 57 | 58 | ``` 59 | GET https://openplzapi.org/de/Streets?postalcode=%5E808&locality=M%C3%BCnchen 60 | ``` 61 | Hier wurden der Zirkumflex `^` des [regulären Ausdrucks](regex.md) mit `%5E` sowie der Umlaut `ü` in "München" mit `%C3%BC` kodiert. 62 | 63 | ## Werkzeug 64 | 65 | Das folgende Werkzeug hilft dir dabei, einen beliebigen Wert zu kodieren. Tippe dazu den Text in das erste Textfeld ein und klicke auf "Kodieren". 66 | 67 | 68 | 69 | 70 | 71 | Das URL-kodierte Ergebnis siehst Du hier: 72 | 73 | 74 | 75 | 86 | 87 | ## Kodierungslisten 88 | 89 | ### Lateinische Zeichen mit Akzenten und Diakritika 90 | 91 | Zeichen | URL-Kodierung | Zeichen | URL-Kodierung 92 | --------- | ------------- | --------- | ------------- 93 | À | `%C3%80` | Á | `%C3%81` 94 | Â | `%C3%82` | Ã | `%C3%83` 95 | Ä | `%C3%84` | Å | `%C3%85` 96 | Æ | `%C3%86` | Ç | `%C3%87` 97 | È | `%C3%88` | É | `%C3%89` 98 | Ê | `%C3%8A` | Ë | `%C3%8B` 99 | Ì | `%C3%8C` | Í | `%C3%8D` 100 | Î | `%C3%8E` | Ï | `%C3%8F` 101 | Ð | `%C3%90` | Ñ | `%C3%91` 102 | Ò | `%C3%92` | Ó | `%C3%93` 103 | Ô | `%C3%94` | Õ | `%C3%95` 104 | Ö | `%C3%96` | Ø | `%C3%98` 105 | Ù | `%C3%99` | Ú | `%C3%9A` 106 | Û | `%C3%9B` | Ü | `%C3%9C` 107 | Ý | `%C3%9D` | Þ | `%C3%9E` 108 | ß | `%C3%9F` | à | `%C3%A0` 109 | á | `%C3%A1` | â | `%C3%A2` 110 | ã | `%C3%A3` | ä | `%C3%A4` 111 | å | `%C3%A5` | æ | `%C3%A6` 112 | ç | `%C3%A7` | è | `%C3%A8` 113 | é | `%C3%A9` | ê | `%C3%AA` 114 | ë | `%C3%AB` | ì | `%C3%AC` 115 | í | `%C3%AD` | î | `%C3%AE` 116 | ï | `%C3%AF` | ð | `%C3%B0` 117 | ñ | `%C3%B1` | ò | `%C3%B2` 118 | ó | `%C3%B3` | ô | `%C3%B4` 119 | õ | `%C3%B5` | ö | `%C3%B6` 120 | ø | `%C3%B8` | ù | `%C3%B9` 121 | ú | `%C3%BA` | û | `%C3%BB` 122 | ü | `%C3%BC` | ý | `%C3%BD` 123 | þ | `%C3%BE` | ÿ | `%C3%BF` 124 | 125 | ### Sonderzeichen 126 | 127 | Zeichen | Bedeutung | URL-Kodierung 128 | ----------- | ---------------------------- | ------------- 129 | Leerzeichen | | `%20` 130 | ! | Ausrufezeichen | `%21` 131 | " | Anführungszeichen (doppelt) | `%22` 132 | \# | Hash-Zeichen | `%23` 133 | $ | Dollar-Zeichen | `%24` 134 | % | Prozentzeichen | `%25` 135 | & | Kaufmännisches Und | `%26` 136 | ' | Apostroph | `%27` 137 | ( | Klammer auf | `%28` 138 | ) | Klammer zu | `%29` 139 | \* | Sternchen | `%2A` 140 | + | Pluszeichen | `%2B` 141 | , | Komma | `%2C` 142 | - | Bindestrich | `%2D` 143 | . | Punkt | `%2E` 144 | / | Schrägstrich | `%2F` 145 | : | Doppelpunkt | `%3A` 146 | ; | Semikolon | `%3B` 147 | < | Kleiner-als-Zeichen | `%3C` 148 | = | Gleichheitszeichen | `%3D` 149 | > | Größer-als-Zeichen | `%3E` 150 | ? | Fragezeichen | `%3F` 151 | @ | At-Zeichen | `%40` 152 | \[ | Eckige Klammer auf | `%5B` 153 | \\ | Rückschrägstrich | `%5C` 154 | ] | Eckige Klammer zu | `%5D` 155 | ^ | Zirkumflex | `%5E` 156 | _ | Unterstrich | `%5F` 157 | \` | Backtick | `%60` 158 | { | Geschweifte Klammer auf | `%7B` 159 | \| | Vertikaler Strich | `%7C` 160 | } | Geschweifte Klammer zu | `%7D` 161 | ~ | Tilde | `%7E` 162 | -------------------------------------------------------------------------------- /de/mkdocs.yml: -------------------------------------------------------------------------------- 1 | # Project information 2 | site_name: OpenPLZ API 3 | site_description: 'Dokumentation des OpenPLZ API Projekts' 4 | site_author: 'STÜBER SYSTEMS GmbH' 5 | site_url: 'https://www.openplzapi.org/' 6 | 7 | # Copyright 8 | copyright: 9 | '© 2025 STÜBER SYSTEMS GmbH : Impressum : Datenschutz' 10 | 11 | # Repository 12 | repo_name: 'Auf GitHub' 13 | repo_url: 'https://github.com/openpotato/openplzapi.website' 14 | 15 | # Theming 16 | theme: 17 | name: material 18 | language: de 19 | features: 20 | - content.code.copy 21 | - navigation.footer 22 | - navigation.instant 23 | - search.highlight 24 | - search.share 25 | - search.suggest 26 | - toc.follow 27 | palette: 28 | - scheme: default 29 | primary: 'green' 30 | accent: 'green' 31 | toggle: 32 | icon: material/brightness-7 33 | name: In den Dunkelmodus wechseln 34 | - scheme: slate 35 | primary: 'green' 36 | accent: 'green' 37 | toggle: 38 | icon: material/brightness-4 39 | name: In den Hellmodus wechseln 40 | font: false 41 | favicon: 'assets/logos/favicon.ico' 42 | logo: 'assets/logos/logo.svg' 43 | include_search_page: false 44 | search_index_only: true 45 | static_templates: 46 | - 404.html 47 | 48 | # Social media & multi language 49 | extra: 50 | social: 51 | - icon: fontawesome/brands/bluesky 52 | link: https://bsky.app/profile/openpotato.org 53 | - icon: fontawesome/brands/mastodon 54 | link: https://fosstodon.org/@openpotato 55 | alternate: 56 | - name: English 57 | link: /en/ 58 | lang: en 59 | - name: Deutsch 60 | lang: de 61 | 62 | # Customization 63 | extra_css: 64 | - assets/css/custom.css 65 | 66 | # Plugins 67 | plugins: 68 | - search 69 | - minify: 70 | minify_html: true 71 | 72 | # Extensions 73 | markdown_extensions: 74 | - admonition 75 | - attr_list 76 | - def_list 77 | - pymdownx.emoji: 78 | emoji_index: !!python/name:material.extensions.emoji.twemoji 79 | emoji_generator: !!python/name:material.extensions.emoji.to_svg 80 | - pymdownx.superfences 81 | - pymdownx.tabbed: 82 | alternate_style: true 83 | 84 | # Navigation 85 | nav: 86 | - Einführung: index.md 87 | - Referenz: 88 | - Deutschland: germany.md 89 | - Liechtenstein: liechtenstein.md 90 | - Schweiz: switzerland.md 91 | - Österreich: austria.md 92 | - Paging: paging.md 93 | - URL-Koderierung: url-encoding.md 94 | - Reguläre Ausdrücke: regex.md 95 | - Volltextsuche: fulltextsearch.md 96 | - Fehlermeldungen: errors.md 97 | - Änderungslog: 98 | - Daten: change-log-data.md 99 | - Web-Service: change-log-webservice.md 100 | - Datenquellen: sources.md 101 | - Client-Bibliotheken: libraries.md 102 | - Community: community.md 103 | - FAQ: faq.md 104 | - API: api.md 105 | -------------------------------------------------------------------------------- /en/docs/api.md: -------------------------------------------------------------------------------- 1 | The complete **OpenPLZ API** is available as an OpenAPI definition and can be tested interactively by means of an automatically generated interface. 2 | 3 | [Test OpenPLZ API](https://openplzapi.org/swagger){ .md-button .md-button--primary } 4 | 5 | !!! note "OpenAPI" 6 | 7 | The [OpenAPI specification](https://spec.openapis.org/oas/latest.html) defines a standardised, programming language-independent interface description for HTTP-based APIs. The specification is monitored and further developed by the [OpenAPI Initiative](https://www.openapis.org/about). 8 | 9 | The monitoring of the OpenHolidays API services is also open source. 10 | 11 | [OpenPLZ API Live Status](https://openpotato.github.io/uptime/){ .md-button .md-button--primary } 12 | -------------------------------------------------------------------------------- /en/docs/assets/css/custom.css: -------------------------------------------------------------------------------- 1 | /* roboto-300 - latin */ 2 | @font-face { 3 | font-family: 'Roboto'; 4 | font-style: normal; 5 | font-weight: 300; 6 | src: local('Roboto Light'), local('Roboto-Light'), 7 | url('../fonts/roboto-v20-latin-300.woff2') format('woff2'), /* Chrome 26+, Opera 23+, Firefox 39+ */ 8 | url('../fonts/roboto-v20-latin-300.woff') format('woff'); /* Chrome 6+, Firefox 3.6+, IE 9+, Safari 5.1+ */ 9 | } 10 | /* roboto-regular - latin */ 11 | @font-face { 12 | font-family: 'Roboto'; 13 | font-style: normal; 14 | font-weight: 400; 15 | src: local('Roboto'), local('Roboto-Regular'), 16 | url('../fonts/roboto-v20-latin-regular.woff2') format('woff2'), /* Chrome 26+, Opera 23+, Firefox 39+ */ 17 | url('../fonts/roboto-v20-latin-regular.woff') format('woff'); /* Chrome 6+, Firefox 3.6+, IE 9+, Safari 5.1+ */ 18 | } 19 | /* roboto-italic - latin */ 20 | @font-face { 21 | font-family: 'Roboto'; 22 | font-style: italic; 23 | font-weight: 400; 24 | src: local('Roboto Italic'), local('Roboto-Italic'), 25 | url('../fonts/roboto-v20-latin-italic.woff2') format('woff2'), /* Chrome 26+, Opera 23+, Firefox 39+ */ 26 | url('../fonts/roboto-v20-latin-italic.woff') format('woff'); /* Chrome 6+, Firefox 3.6+, IE 9+, Safari 5.1+ */ 27 | } 28 | /* roboto-700 - latin */ 29 | @font-face { 30 | font-family: 'Roboto'; 31 | font-style: normal; 32 | font-weight: 700; 33 | src: local('Roboto Bold'), local('Roboto-Bold'), 34 | url('../fonts/roboto-v20-latin-700.woff2') format('woff2'), /* Chrome 26+, Opera 23+, Firefox 39+ */ 35 | url('../fonts/roboto-v20-latin-700.woff') format('woff'); /* Chrome 6+, Firefox 3.6+, IE 9+, Safari 5.1+ */ 36 | } 37 | /* roboto-mono-regular - latin */ 38 | @font-face { 39 | font-family: 'Roboto Mono'; 40 | font-style: normal; 41 | font-weight: 400; 42 | src: local(''), 43 | url('../fonts/roboto-mono-v12-latin-regular.woff2') format('woff2'), /* Chrome 26+, Opera 23+, Firefox 39+ */ 44 | url('../fonts/roboto-mono-v12-latin-regular.woff') format('woff'); /* Chrome 6+, Firefox 3.6+, IE 9+, Safari 5.1+ */ 45 | } 46 | /* Regular font */ 47 | body, input { 48 | font-family: 'Roboto', -apple-system, Helvetica, Arial, sans-serif; 49 | } 50 | /* Proportional font */ 51 | pre, code, kbd { 52 | font-family: 'Roboto Mono', SFMono-Regular, Consolas, Menlo, monospace; 53 | } 54 | -------------------------------------------------------------------------------- /en/docs/assets/fonts/roboto-mono-v12-latin-regular.woff: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/openpotato/openplzapi.website/b14265ec347b62cd29364d4a50de92dfd2774454/en/docs/assets/fonts/roboto-mono-v12-latin-regular.woff -------------------------------------------------------------------------------- /en/docs/assets/fonts/roboto-mono-v12-latin-regular.woff2: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/openpotato/openplzapi.website/b14265ec347b62cd29364d4a50de92dfd2774454/en/docs/assets/fonts/roboto-mono-v12-latin-regular.woff2 -------------------------------------------------------------------------------- /en/docs/assets/fonts/roboto-v20-latin-300.woff: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/openpotato/openplzapi.website/b14265ec347b62cd29364d4a50de92dfd2774454/en/docs/assets/fonts/roboto-v20-latin-300.woff -------------------------------------------------------------------------------- /en/docs/assets/fonts/roboto-v20-latin-300.woff2: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/openpotato/openplzapi.website/b14265ec347b62cd29364d4a50de92dfd2774454/en/docs/assets/fonts/roboto-v20-latin-300.woff2 -------------------------------------------------------------------------------- /en/docs/assets/fonts/roboto-v20-latin-700.woff: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/openpotato/openplzapi.website/b14265ec347b62cd29364d4a50de92dfd2774454/en/docs/assets/fonts/roboto-v20-latin-700.woff -------------------------------------------------------------------------------- /en/docs/assets/fonts/roboto-v20-latin-700.woff2: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/openpotato/openplzapi.website/b14265ec347b62cd29364d4a50de92dfd2774454/en/docs/assets/fonts/roboto-v20-latin-700.woff2 -------------------------------------------------------------------------------- /en/docs/assets/fonts/roboto-v20-latin-italic.woff: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/openpotato/openplzapi.website/b14265ec347b62cd29364d4a50de92dfd2774454/en/docs/assets/fonts/roboto-v20-latin-italic.woff -------------------------------------------------------------------------------- /en/docs/assets/fonts/roboto-v20-latin-italic.woff2: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/openpotato/openplzapi.website/b14265ec347b62cd29364d4a50de92dfd2774454/en/docs/assets/fonts/roboto-v20-latin-italic.woff2 -------------------------------------------------------------------------------- /en/docs/assets/fonts/roboto-v20-latin-regular.woff: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/openpotato/openplzapi.website/b14265ec347b62cd29364d4a50de92dfd2774454/en/docs/assets/fonts/roboto-v20-latin-regular.woff -------------------------------------------------------------------------------- /en/docs/assets/fonts/roboto-v20-latin-regular.woff2: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/openpotato/openplzapi.website/b14265ec347b62cd29364d4a50de92dfd2774454/en/docs/assets/fonts/roboto-v20-latin-regular.woff2 -------------------------------------------------------------------------------- /en/docs/assets/logos/favicon.ico: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/openpotato/openplzapi.website/b14265ec347b62cd29364d4a50de92dfd2774454/en/docs/assets/logos/favicon.ico -------------------------------------------------------------------------------- /en/docs/assets/logos/logo.svg: -------------------------------------------------------------------------------- 1 | 2 | 3 | -------------------------------------------------------------------------------- /en/docs/austria.md: -------------------------------------------------------------------------------- 1 | The OpenPLZ API data directory for [Austria](https://en.wikipedia.org/wiki/Austria) includes street names, postal codes, localities, and administrative divisions (municipalities, districts, and federal states). 2 | 3 | ## Administrative Structure 4 | 5 | Austria's administrative structure is based on a federal system divided into multiple levels. Each level has clearly defined competencies and responsibilities regulated by the constitution. 6 | 7 | **Federation (Bund)** 8 | 9 | : The highest administrative unit of the state. The federation has a central government and is responsible for overarching matters such as foreign policy, defense, and justice. 10 | 11 | **Federal Provinces (Bundesländer)** 12 | 13 | : The federal units below the federation, consisting of 9 states. Each state has its own constitution, government, and state parliament. The states have independent competencies, particularly in areas such as education and culture. 14 | 15 | **Districts (Bezirke)** 16 | 17 | : An intermediate administrative level between states and municipalities, consisting of political districts. Districts do not have legislative power but manage tasks exceeding municipal responsibilities. District administrative authorities are either district commissions (Bezirkshauptmannschaften) or magistrates in statutory cities. 18 | 19 | **Municipalities (Gemeinden)** 20 | 21 | : The smallest administrative units with self-governing authority. There are around 2,000 municipalities in Austria. Each municipality has an elected local administration led by a mayor. 22 | 23 | **Statutory Cities (Statutarstädte)** 24 | 25 | : Cities that fulfill the responsibilities of both a municipality and a district. Austria has 15 statutory cities, including Vienna, which is both a city and a federal state. 26 | 27 | ## Requesting Federal Provinces 28 | 29 | The nine federal provinces of Austria can be queried through the following API endpoint: 30 | 31 | !!! info "" 32 | 33 | **`openplzapi.org/at/FederalProvinces`** 34 | 35 | : List of all federal provinces in Austria. 36 | 37 | For each federal province, the following attributes are provided: 38 | 39 | + `key (string)`: Federal province code (1-digit) 40 | + `name (string)`: Name of the federal province 41 | 42 | Example request for the complete list of federal provinces: 43 | 44 | ``` 45 | GET https://openplzapi.org/at/FederalProvinces 46 | ``` 47 | 48 | ## Requesting Districts 49 | 50 | Districts in Austria can be queried through the following API endpoint: 51 | 52 | !!! info "" 53 | 54 | **`openplzapi.org/at/FederalProvinces/{stateCode}/Districts`** 55 | 56 | : List of all districts within a federal province. A province code (1-digit) is required as a parameter. The query is subject to [paging](paging.md). 57 | 58 | For each district, the following attributes are provided: 59 | 60 | + `key (string)`: District code (3-digit) 61 | + `code (string)`: District coding (3-digit) 62 | + `name (string)`: Name of the district 63 | + `federalProvince.key (string)`: Province code (1-digit) 64 | + `federalProvince.name (string)`: Name of the federal province 65 | 66 | Example request for districts in Vienna (Province Code: `7`) 67 | 68 | ``` 69 | GET https://openplzapi.org/at/FederalProvinces/7/Districts 70 | ``` 71 | 72 | ## Requesting Municipalities 73 | 74 | Municipalities in Austria can be queried through the following API endpoints: 75 | 76 | !!! info "" 77 | 78 | **`openplzapi.org/at/FederalProvinces/{stateCode}/Municipalities`** 79 | 80 | : List of all municipalities within a federal province. A province code (1-digit) is required as a parameter. The query is subject to [paging](paging.md). 81 | 82 | **`openplzapi.org/at/Districts/{districtCode}/Municipalities`** 83 | 84 | : List of all municipalities within a district. A district code **or** district coding (both 3-digit) is required as a parameter. The query is subject to [paging](paging.md). 85 | 86 | For each municipality, the following attributes are provided: 87 | 88 | + `key (string)`: Municipality code (5-digit) 89 | + `code (string)`: Municipality coding (5-digit) 90 | + `name (string)`: Name of the municipality 91 | + `postalCode (string)`: Postal code of the municipal office 92 | + `multiplePostalCodes (bool)`: Does the municipality cover multiple postal codes? 93 | + `district.key (string)`: District code (3-digit) 94 | + `district.code (string)`: District coding (3-digit) 95 | + `district.name (string)`: Name of the district 96 | + `federalProvince.key (string)`: Province code (1-digit) 97 | + `federalProvince.name (string)`: Name of the federal province 98 | 99 | Example request for municipalities in Vienna (Province Code: `7`) 100 | 101 | ``` 102 | GET https://openplzapi.org/at/FederalProvinces/7/Municipalities 103 | ``` 104 | 105 | ## Requesting Postal Codes and Localities 106 | 107 | Postal codes and localities in Austria can be queried through the following API endpoints: 108 | 109 | !!! info "" 110 | 111 | **`openplzapi.org/at/FederalProvinces/{stateCode}/Localities`** 112 | 113 | : List of all localities within a federal province. A province code (1-digit) is required as a parameter. The query is subject to [paging](paging.md). 114 | 115 | **`openplzapi.org/at/Districts/{districtCode}/Localities`** 116 | 117 | : List of all localities within a district. A district code **or** district coding (both 3-digit) is required as a parameter. The query is subject to [paging](paging.md). 118 | 119 | **`openplzapi.org/at/Localities?postalCode={postalCode}&name={localityName}`** 120 | 121 | : Searches for all localities that match the postal code and/or locality name. The parameters `postalCode` and `name` can be used together or independently. Both parameters support [regular expressions](regex.md). The query is subject to [paging](paging.md). 122 | 123 | For each locality, the following attributes are provided: 124 | 125 | + `key (string)`: Locality code 126 | + `name (string)`: Name of the locality 127 | + `postalcode (string)`: Postal code of the locality 128 | + `municipality.key (string)`: Municipality code (5-digit) 129 | + `municipality.code (string)`: Municipality coding (5-digit) 130 | + `municipality.name (string)`: Name of the municipality 131 | + `district.key (string)`: District code (3-digit) 132 | + `district.code (string)`: District coding (3-digit) 133 | + `district.name (string)`: Name of the district 134 | + `federalProvince.key (string)`: Province code (1-digit) 135 | + `federalProvince.name (string)`: Name of the federal province 136 | 137 | Example request for postal code *1010* 138 | 139 | ``` 140 | GET https://openplzapi.org/at/Localities?postalCode=1010 141 | ``` 142 | 143 | Example request for all postal codes starting with *10*. The [regular expression](regex.md) `^10` is [URL-encoded](url-encoding.md): 144 | 145 | ``` 146 | GET https://openplzapi.org/at/Localities?postalCode=%5E10 147 | ``` 148 | 149 | ## Requesting Streets 150 | 151 | Streets in Austria can be queried through the following API endpoints: 152 | 153 | !!! info "" 154 | 155 | **`openplzapi.org/at/Streets?name={streetName}&postalCode={postalCode}&locality={localityName}`** 156 | 157 | : Searches for all streets matching the street name and/or postal code and/or locality name. The parameters `name`, `postalCode`, and `locality` can be used together or independently. All three parameters support [regular expressions](regex.md). The query is subject to [paging](paging.md). 158 | 159 | **`openplzapi.org/at/FullTextSearch?searchTerm={searchTerm}`** 160 | 161 | : Searches for streets using [full-text search](fulltextsearch.md) across street name, postal code, and locality name. The query is subject to [paging](paging.md). 162 | 163 | For each street, the following attributes are provided: 164 | 165 | + `key (string)`: Street code 166 | + `name (string)`: Name of the street 167 | + `postalcode (string)`: Postal code of the locality 168 | + `locality (string)`: Name of the locality 169 | + `municipality.key (string)`: Municipality code (5-digit) 170 | + `municipality.code (string)`: Municipality coding (5-digit) 171 | + `municipality.name (string)`: Name of the municipality 172 | + `district.key (string)`: District code (3-digit) 173 | + `district.code (string)`: District coding (3-digit) 174 | + `district.name (string)`: Name of the district 175 | + `federalProvince.key (string)`: Province code (1-digit) 176 | + `federalProvince.name (string)`: Name of the federal province 177 | 178 | Example request for the street *Alexander-Poch-Platz* 179 | 180 | ``` 181 | GET https://openplzapi.org/at/Streets?name=Alexander-Poch-Platz 182 | ``` 183 | 184 | Example request for all streets in Vienna starting with *A* and ending with *Platz*. The [regular expression](regex.md) `^A.*Platz$` is [URL-encoded](url-encoding.md): 185 | 186 | ``` 187 | GET https://openplzapi.org/at/Streets?name=%5EA.%2APlatz%24&locality=Wien 188 | ``` 189 | 190 | Example full-text search with the term `Wien Alfred Dallinger Platz`. The search term is [URL-encoded](url-encoding.md): 191 | 192 | ``` 193 | GET https://openplzapi.org/at/FullTextSearch?searchTerm=Wien%20Alfred%20Dallinger%20Platz 194 | ``` -------------------------------------------------------------------------------- /en/docs/change-log-data.md: -------------------------------------------------------------------------------- 1 | # Current data 2 | 3 | The current dataset (see also [data sources](sources.md)): 4 | 5 | Country | Data source | Release 6 | ----------------------- | ---------------------- | ------- 7 | :flag_at: Austria | Municipality directory | 2025-02-27 8 | :flag_at: Austria | Street directory | 2025-02-27 9 | :flag_de: Germany | Municipality directory | 2025-01-29 10 | :flag_de: Germany | Street directory | 2025-03-04 11 | :flag_li: Liechtenstein | Municipality directory | March 1996 12 | :flag_li: Liechtenstein | Street directory | 2025-03-04 13 | :flag_ch: Switzerland | Municipality directory | 2025-03-04 14 | :flag_ch: Switzerland | Street directory | 2025-03-04 15 | 16 | -------------------------------------------------------------------------------- /en/docs/change-log-webservice.md: -------------------------------------------------------------------------------- 1 | # Change Log - Web Service 2 | 3 | The OpenPLZ API Web Service is [Open Source](https://github.com/openpotato/openplzapi) on GitHub. The detailed [commit history](https://github.com/openpotato/openplzapi/commits/develop/) can be viewed there. This change log serves as a summarised overview of the changes. 4 | 5 | We largely adhere to the recommendations from the community project [Keep a Changelog](https://keepachangelog.com). 6 | 7 | ## 1.1.0 _ March 05, 2025 8 | 9 | **Changed:** 10 | 11 | + Updated source for GV100AD 12 | + Updated dependencies 13 | + Minor refactorings 14 | 15 | ## 1.0.0 _ December 16, 2024 16 | 17 | **Added:** 18 | 19 | + Added HTTP Access-Control-Expose-Headers response header 20 | 21 | **Changed:** 22 | 23 | + Breaking API change: Missing paging endpoint for `at/Districts/{key}/Localities` 24 | 25 | **Fixed:** 26 | 27 | + Bug fix for Swiss CSV response format 28 | 29 | ## 0.1.0 _ December 02, 2024 30 | 31 | **Changed:** 32 | 33 | + Update to .NET 9 34 | + Breaking API change: Communes, districts and cantons for Switzerland have now all been given the properties `HistoricalCode` and `ShortName`. The `Code` property for cantons has been removed. 35 | + Refactoring of the source for the Swiss commune directory. The API of the Federal Statistical Office (FSO) is now accessed directly. 36 | 37 | ## 0.0.6 _ November 25, 2024 38 | 39 | **Added:** 40 | 41 | + New API endpoints `FullTextSearch` for full-text search via street, location and postal code for all countries. 42 | + Additional paging information `x-page`, `x-page-size`, `x-total-pages` and `x-total-count` in the HTTP response headers of the API (only applies to endpoints with pagination). 43 | + Support for [RFC 9457](https://www.rfc-editor.org/rfc/rfc9457) (Problem Details for HTTP APIs) 44 | 45 | **Fixed:** 46 | 47 | + Fixed incorrect URL for API endpoint `li/Communes` (was previously `li/Cantons/Communes`). 48 | 49 | ## 0.0.5 _ September 20, 2024 50 | 51 | **Added:** 52 | 53 | + Street entities for Germany now contain additional information on borough and/or suburb (if available in OpenStreetMap) 54 | + Support for streets and postal codes from Liechtenstein 55 | 56 | **Changed:** 57 | 58 | + Update of the data sources. 59 | 60 | ## 0.0.4 _ November 23, 2023 61 | 62 | **Added:** 63 | 64 | + New API endpoints for `Locality` entities 65 | + Paging for nearly all API endpoints 66 | 67 | **Changed:** 68 | 69 | + Update to .NET 8 70 | 71 | ## 0.0.3 _ September 27, 2023 72 | 73 | **Added:** 74 | 75 | + CSV as additional output format 76 | 77 | **Changed:** 78 | 79 | + Update of the data sources. 80 | 81 | ## 0.0.2 _ February 05, 2023 82 | 83 | **Added:** 84 | 85 | + `Street` entities and `Locality` entities now contain more detailed information on municipalities, districts and federal states or cantons. 86 | + [CORS](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS) support added. 87 | 88 | ## 0.0.1 _ December 09, 2022 89 | 90 | First publication -------------------------------------------------------------------------------- /en/docs/community.md: -------------------------------------------------------------------------------- 1 | # Community 2 | 3 | OpenPLZ API is open data, the infrastructure is open source. A project like this lives from the users who use it. We welcome feedback and help of any kind: 4 | 5 | + Create an issue in the [GitHub Issue Tracker](https://github.com/openpotato/openplzapi/issues). 6 | + Start a discussion under [GitHub Discussions](https://github.com/openpotato/openplzapi.website/discussions). 7 | + Initiate a [Pull Request](https://github.com/openpotato/openplzapi/pulls). 8 | -------------------------------------------------------------------------------- /en/docs/errors.md: -------------------------------------------------------------------------------- 1 | # Error Messages 2 | 3 | The OpenPLZ API returns error messages as JSON objects formatted according to RFC 9457. 4 | 5 | ## What is RFC 9457? 6 | 7 | [RFC 9457](https://www.rfc-editor.org/rfc/rfc9457) is a standard by the Internet Engineering Task Force (IETF) that defines a structured format for representing errors in HTTP APIs. 8 | 9 | ## Problem Details 10 | 11 | At the core of RFC 9457 is the *Problem Details* object, a JSON document included in the response body of an API query when errors occur. The OpenPLZ API implements it with the following fields: 12 | 13 | `type` (string) 14 | 15 | : A URI reference that identifies the type of error. This is typically a reference to the specification of the HTTP status code on the web. 16 | 17 | Example: `"https://tools.ietf.org/html/rfc9110#section-15.5.1"` 18 | 19 | `title` (string) 20 | 21 | : A short, human-readable summary of the problem. 22 | 23 | Example: `"One or more validation errors occurred."` 24 | 25 | `status` (integer) 26 | 27 | : The HTTP status code describing the error. It should match the status code in the HTTP response header. 28 | 29 | Example: `400` 30 | 31 | `errors` (object) 32 | 33 | : (Optional) A JSON object containing additional details about the error. 34 | 35 | Example: 36 | ```json 37 | { 38 | "pageSize": [ 39 | "The field pageSize must be between 1 and 50." 40 | ] 41 | } 42 | ``` 43 | 44 | `traceId` (string) 45 | 46 | : A unique identifier that can be used for tracing in distributed systems. 47 | 48 | Example: `"00-abc123def456789ghi-xyz987uvw654321tqr-01"` 49 | 50 | !!! note "Extension Members" 51 | 52 | The fields `type`, `title`, and `status` are well-defined in RFC 9457. The fields `errors` and `traceId` are known as *Extension Members*, which extend the standard fields. 53 | 54 | ## Example 55 | 56 | The API call 57 | 58 | ``` 59 | https://openplzapi.org/de/Streets?name=Pariser%20Platz&locality=Berlin&page=1&pageSize=99 60 | ``` 61 | 62 | results in the following error message: 63 | 64 | ``` json 65 | { 66 | "type": "https://tools.ietf.org/html/rfc9110#section-15.5.1", 67 | "title": "One or more validation errors occurred.", 68 | "status": 400, 69 | "errors": { 70 | "pageSize": [ 71 | "The field pageSize must be between 1 and 50." 72 | ] 73 | }, 74 | "traceId": "00-0274bb16dcdf462bf27a7faedeacc79f-05c5cd5b5d411f8e-00" 75 | } 76 | ``` 77 | 78 | Analysis of the error: 79 | 80 | + The server cannot process the request because it is not properly formulated (HTTP error code 400: Bad Request). 81 | 82 | + It is evident that there is an issue with the validation of the query parameters ("One or more validation errors occurred."). 83 | 84 | + And indeed, the `pageSize` parameter has a value (99) outside the valid range (only 1–50). 85 | -------------------------------------------------------------------------------- /en/docs/faq.md: -------------------------------------------------------------------------------- 1 | # Frequently asked questions (FAQ) 2 | 3 | Is the OpenPLZ API really free? Where does all the data come from? In our FAQ you will find answers to the most frequently asked questions about the OpenPLZ API project. 4 | 5 | ## Can I use the OpenPLZ API free of charge? 6 | 7 | Yes, the OpenPLZ API project is open data, its use is free of charge and also permitted in commercial projects. All data comes from public sources and is documented [here](sources.md). The processed data is licensed under the [ODC Open Database Licence (ODbL)](https://raw.githubusercontent.com/openpotato/openplzapi.data/refs/heads/main/LICENSE). 8 | 9 | ## Where is the OpenPLZ API hosted? 10 | 11 | The OpenPLZ API web service runs on a Linux server operated by the German internet service provider [STRATO](https://www.strato.de/). The data centre is located in Germany. 12 | 13 | ## Where does the data come from? 14 | 15 | All data from the OpenPLZ API project comes from public sources and is documented [here](sources.md). The processed data is available under the [ODC Open Database Licence (ODbL)](https://raw.githubusercontent.com/openpotato/openplzapi.data/refs/heads/main/LICENSE). 16 | 17 | ## How often is the data updated? 18 | 19 | The data of the OpenPLZ API project is updated regularly. We are currently aiming for quarterly updates. The current status of the data is always documented in the [change log](change-log.md). 20 | 21 | ## I have found an error! 22 | 23 | Please let us know. Preferably via [GitHub issue tracker](https://github.com/openpotato/openplzapi/issues). 24 | 25 | ## I want to participate! 26 | 27 | Do you have a suggestion for improvement? Always send it to us, preferably as a discussion post at [GitHub](https://github.com/openpotato/openplzapi.website/discussions). 28 | 29 | Even better, have you corrected a bug or programmed an improvement? Great, we're waiting for your [pull request on GitHub](https://github.com/openpotato/openplzapi/pulls). 30 | 31 | ## Still have questions? 32 | 33 | You can ask us at any time. Use the [GitHub issue tracker](https://github.com/openpotato/openplzapi/issues). Would you rather write us an email? Feel free to write to us at `openpotato@stueber.de`. 34 | -------------------------------------------------------------------------------- /en/docs/fulltextsearch.md: -------------------------------------------------------------------------------- 1 | # Full text search 2 | 3 | For each country supported in the OpenPLZ API project there is a special API endpoint for **full text search**. 4 | 5 | ## What is full-text search? 6 | 7 | Full-text search in relational databases allows text in one or more columns to be searched based on the actual meaning of the words rather than a simple string match. The aim is to return the most relevant results possible when searching for specific terms - similar to a search engine. 8 | 9 | For example, a search for "Monchengladbach" will also return results for "Mönchengladbach". 10 | 11 | You can also enter the street, postal code and/or location in any order. The search entry 12 | 13 | ``` 14 | Berlin Pariser Platz 15 | ``` 16 | 17 | returns the same result as 18 | 19 | ``` 20 | Pariser Platz, Berlin 21 | ``` 22 | 23 | ## How exactly does the full-text search work? 24 | 25 | We use the PostgreSQL full-text search in the background, more precisely the function [`websearch_to_tsquery`](https://www.postgresql.org/docs/current/textsearch-controls.html#TEXTSEARCH-PARSING-QUERIES). This function allows the input of unformatted text and converts it into the appropriate target format for PostgreSQL: 26 | 27 | + Text that is not in inverted commas is converted to terms separated by `&` operators, as when processed by `plainto_tsquery`. 28 | 29 | + Text in ‘inverted commas’ is converted into terms separated by `<->` operators, as if they were being processed by `phraseto_tsquery`. 30 | 31 | + An `OR` is converted to the `|` operator. 32 | 33 | + A hyphen `-` is converted into the operator `!`. 34 | 35 | + Other special characters, e.g. full stop, comma, exclamation mark etc. are ignored. 36 | 37 | ## Where can I find the full text search? 38 | 39 | The following API endpoints allow a full text search via street name, postal code and location name: 40 | 41 | + `at/FullTextSearch` 42 | + `ch/FullTextSearch` 43 | + `de/FullTextSearch` 44 | + `li/FullTextSearch` 45 | 46 | It's best just to try it out. 47 | -------------------------------------------------------------------------------- /en/docs/germany.md: -------------------------------------------------------------------------------- 1 | The OpenPLZ API data directory for [Germany](https://en.wikipedia.org/wiki/Germany) includes street names, postal codes, localities, and administrative divisions (municipalities, municipal associations, districts, government regions, and federal states). 2 | 3 | ## Administrative Structure 4 | 5 | Germany's administrative structure is based on a federal system governed by the Basic Law (Grundgesetz). It is divided into several levels, each with specific competencies and responsibilities. 6 | 7 | **Federation (Bund)** 8 | 9 | : The highest level of administration and legislation in Germany. The federation is responsible for overarching matters such as foreign policy, defense, and monetary order. Legislation is carried out by the Bundestag and Bundesrat, while the executive branch is headed by the federal government. 10 | 11 | **Federal States (Bundesländer)** 12 | 13 | : The federal units below the federation, consisting of 16 federal states. Each state has its own constitution, government, and state parliament. The states have exclusive competencies, particularly in areas such as education, police, and cultural affairs. 14 | 15 | **Government Regions (Regierungsbezirke)** 16 | 17 | : A middle level of administration positioned between the state and district levels in some federal states. Government regions exist in only four of the 16 federal states and primarily coordinate state administration. They do not have independent legislative powers. 18 | 19 | **Districts (Kreise)** 20 | 21 | : A municipal administrative unit between government regions (where applicable) and municipalities. 22 | 23 | The main types of districts: 24 | 25 | + Rural districts (Landkreise) 26 | + Urban districts (kreisfreie Städte), which perform the functions of both districts and municipalities. 27 | 28 | **Municipalities (Gemeinden)** 29 | 30 | : The smallest administrative units with extensive self-governing rights. Municipalities are responsible for local administration and are led by an elected municipal council and usually a mayor. 31 | 32 | **Municipal Associations (Gemeindeverbände)** 33 | 34 | : Associations of municipalities formed to jointly carry out specific tasks. Municipal associations, such as administrative communities or special-purpose associations, are typically limited to particular administrative functions. 35 | 36 | ## Requesting Federal States 37 | 38 | The 16 federal states of Germany can be queried through the following API endpoint: 39 | 40 | !!! info "" 41 | 42 | **`openplzapi.org/de/FederalStates`** 43 | 44 | : List of all federal states in Germany. 45 | 46 | For each federal state, the following attributes are provided: 47 | 48 | + `key (string)`: Regional code (2-digit) 49 | + `name (string)`: Name of the federal state 50 | + `seatOfGovernment (string)`: Seat of government of the federal state 51 | 52 | Example reqeust for the complete list of federal states: 53 | 54 | ``` 55 | GET https://openplzapi.org/de/FederalStates 56 | ``` 57 | 58 | ## Requesting Government Regions 59 | 60 | Government regions can be queried through the following API endpoint: 61 | 62 | !!! info "" 63 | 64 | **`openplzapi.org/de/FederalStates/{stateCode}/GovernmentRegions`** 65 | 66 | : List of all government regions within a federal state. A state code (2-digit) is required as a parameter. The query is subject to [paging](paging.md). 67 | 68 | For each government region, the following attributes are provided: 69 | 70 | + `key (string)`: Regional code (3-digit) 71 | + `name (string)`: Name of the government region 72 | + `administrativeHeadquarters (string)`: Administrative headquarters of the government region 73 | + `federalState.key (string)`: State code (2-digit) 74 | + `federalState.name (string)`: Name of the federal state 75 | 76 | !!! note "Government Regions" 77 | 78 | Please note that government regions exist only in four federal states: **Baden-Württemberg**, **Bavaria**, **Hesse**, and **North Rhine-Westphalia**. In **Lower Saxony**, **Rhineland-Palatinate**, and **Saxony**, government regions have been officially abolished but are still included in the municipal directory for statistical purposes and can therefore be queried here. 79 | 80 | Example request for government tegions in Bavaria (State Code: `09`) 81 | 82 | ``` 83 | GET https://openplzapi.org/de/FederalStates/09/GovernmentRegions 84 | ``` 85 | 86 | ## Requesting Districts 87 | 88 | Districts can be queried through the following API endpoints: 89 | 90 | !!! info "" 91 | 92 | **`openplzapi.org/de/FederalStates/{stateCode}/Districts`** 93 | 94 | : List of all districts within a federal state. A state code (2-digit) is required as a parameter. The query is subject to [paging](paging.md). 95 | 96 | **`openplzapi.org/de/GovernmentRegions/{regionCode}/Districts`** 97 | 98 | : List of all districts within a government region. A region code (3-digit) is required as a parameter. The query is subject to [paging](paging.md). 99 | 100 | For each district, the following attributes are provided: 101 | 102 | + `key (string)`: Regional code (5-digit) 103 | + `name (string)`: Name of the district 104 | + `type (string)`: Type of the district. Possible values: 105 | + `Kreisfreie Stadt` (urban district) 106 | + `Stadtkreis` (city district) 107 | + `Kreis` (district) 108 | + `Landkreis` (rural district) 109 | + `Regionalverband` (regional association) 110 | + `administrativeHeadquarters (string)`: Administrative headquarters of the district 111 | + `governmentRegion.key (string)`: Regional code of the government region (3-digit) 112 | + `governmentRegion.name (string)`: Name of the government region 113 | + `federalState.key (string)`: State code (2-digit) 114 | + `federalState.name (string)`: Name of the federal state 115 | 116 | Example request for districts in Rhineland-Palatinate (State Code: `07`) 117 | 118 | ``` 119 | GET https://openplzapi.org/de/FederalStates/07/Districts 120 | ``` 121 | 122 | ## Requesting Municipalities 123 | 124 | Municipalities can be queried through the following API endpoints: 125 | 126 | !!! info "" 127 | 128 | **`openplzapi.org/de/FederalStates/{stateCode}/Municipalites`** 129 | 130 | : List of all municipalities within a federal state. A state code (2-digit) is required as a parameter. The query is subject to [paging](paging.md). 131 | 132 | **`openplzapi.org/de/GovernmentRegions/{regionCode}/Municipalites`** 133 | 134 | : List of all municipalities within a government region. A region code (3-digit) is required as a parameter. The query is subject to [paging](paging.md). 135 | 136 | **`openplzapi.org/de/Districts/{districtCode}/Municipalites`** 137 | 138 | : List of all municipalities within a district. A district code (5-digit) is required as a parameter. The query is subject to [paging](paging.md). 139 | 140 | For each municipality, the following attributes are provided: 141 | 142 | + `key (string)`: Regional code (8-digit) 143 | + `name (string)`: Name of the municipality 144 | + `type (string)`: Type of the municipality. Possible values: 145 | + `Markt` (market town) 146 | + `Kreisfreie Stadt` (urban district) 147 | + `Stadtkreis` (city district) 148 | + `Stadt` (town) 149 | + `Kreisangehörige Gemeinde` (municipality within a district) 150 | + `Gemeindefreies Gebiet (bewohnt)` (unincorporated area, inhabited) 151 | + `Gemeindefreies Gebiet (unbewohnt)` (unincorporated area, uninhabited) 152 | + `Große Kreisstadt` (large district town) 153 | + `postalCode (string)`: Postal code of the administrative seat (if multiple postal codes exist) 154 | + `multiplePostalCodes (bool)`: Does the municipality include more than one postal code? 155 | + `association.key (string)`: Combination of the district regional code and the municipal association key (8-digit) 156 | + `association.name (string)`: Name of the municipal association 157 | + `district.key (string)`: District regional code (5-digit) 158 | + `district.name (string)`: Name of the district 159 | + `governmentRegion.key (string)`: Regional code of the government region (3-digit) 160 | + `governmentRegion.name (string)`: Name of the government region 161 | + `federalState.key (string)`: State code (2-digit) 162 | + `federalState.name (string)`: Name of the federal state 163 | 164 | Example request for municipalities in Rhineland-Palatinate (State Code: `07`): 165 | 166 | ``` 167 | GET https://openplzapi.org/de/FederalStates/07/Municipalites 168 | ``` 169 | 170 | ## Requesting Municipal Associations 171 | 172 | Municipal associations can be queried through the following API endpoints: 173 | 174 | !!! info "" 175 | 176 | **`openplzapi.org/de/FederalStates/{stateCode}/MunicipalAssociations`** 177 | 178 | : List of all municipal associations within a federal state. A state code (2-digit) is required as a parameter. The query is subject to [paging](paging.md). 179 | 180 | **`openplzapi.org/de/GovernmentRegions/{regionCode}/MunicipalAssociations`** 181 | 182 | : List of all municipal associations within a government region. A region code (3-digit) is required as a parameter. The query is subject to [paging](paging.md). 183 | 184 | **`openplzapi.org/de/Districts/{districtCode}/MunicipalAssociations`** 185 | 186 | : List of all municipal associations within a district. A district code (5-digit) is required as a parameter. The query is subject to [paging](paging.md). 187 | 188 | For each municipal association, the following attributes are provided: 189 | 190 | + `key (string)`: Combination of the district regional code and the municipal association key (8-digit) 191 | + `name (string)`: Name of the municipal association 192 | + `type (string)`: Type of the municipal association. Possible values: 193 | + `Amt` 194 | + `Samtgemeinde` (joint municipality) 195 | + `Verbandsgemeinde` (collective municipality) 196 | + `Verwaltungsgemeinschaft` (administrative community) 197 | + `Kirchspielslandgemeinde` (church parish land municipality) 198 | + `Verwaltungsverband` (administrative association) 199 | + `VG Trägermodell` (VG sponsor model) 200 | + `Erfüllende Gemeinde` (fulfilling municipality) 201 | + `administrativeHeadquarters (string)`: Administrative headquarters of the municipal association 202 | + `district.key (string)`: Regional code of the district (5-digit) 203 | + `district.name (string)`: Name of the district 204 | + `governmentRegion.key (string)`: Regional code of the government region (3-digit) 205 | + `governmentRegion.name (string)`: Name of the government region 206 | + `federalState.key (string)`: State code (2-digit) 207 | + `federalState.name (string)`: Name of the federal state 208 | 209 | Example request for municipal associations in Bavaria (State Code: `09`) 210 | 211 | ``` 212 | https://openplzapi.org/de/FederalStates/09/GovernmentRegions 213 | ``` 214 | 215 | ## Requesting Postal Codes and Localities 216 | 217 | Postal codes and localities can be queried through the following API endpoints: 218 | 219 | !!! info "" 220 | 221 | **`openplzapi.org/de/FederalStates/{key}/Localities`** 222 | 223 | : List of all localities within a federal state. A state code (2-digit) is required as a parameter. The query is subject to [paging](paging.md). 224 | 225 | **`openplzapi.org/de/GovernmentRegions/{regionCode}/Localities`** 226 | 227 | : List of all localities within angovernment region. A region code (3-digit) is required as a parameter. The query is subject to [paging](paging.md). 228 | 229 | **`openplzapi.org/de/Districts/{districtCode}/Localities`** 230 | 231 | : List of all localities within a district. A district code (5-digit) is required as a parameter. The query is subject to [paging](paging.md). 232 | 233 | **`openplzapi.org/de/Localities?postalCode={postalCode}&name={localityName}`** 234 | 235 | : Searches for all localities that match the postal code and/or locality name. The parameters `postalCode` and `name` can be used together or independently. Both parameters also support [regular expressions](regex.md). The query is subject to [paging](paging.md). 236 | 237 | For each locality, the following attributes are provided: 238 | 239 | + `name (string)`: Name of the locality 240 | + `postalcode (string)`: Postal code of the locality 241 | + `municipality.key (string)`: Regional code of the municipality (8-digit) 242 | + `municipality.name (string)`: Name of the municipality 243 | + `district.key (string)`: Regional code of the district (5-digit) 244 | + `district.name (string)`: Name of the district 245 | + `governmentRegion.key (string)`: Regional code of the government region (3-digit) 246 | + `governmentRegion.name (string)`: Name of the government region 247 | + `federalState.key (string)`: State code (2-digit) 248 | + `federalState.name (string)`: Name of the federal state 249 | 250 | Example request for postal code *13156* 251 | 252 | ``` 253 | GET https://openplzapi.org/de/Localities?postalCode=13156 254 | ``` 255 | 256 | Example request for all German postal codes starting with *13*. The regular expression `^13` is [URL-encoded](url-encoding.md): 257 | 258 | ``` 259 | GET https://openplzapi.org/de/Localities?postalCode=%5E13 260 | ``` 261 | 262 | ## Requesting Streets 263 | 264 | Streets can be queried through the following API endpoints: 265 | 266 | !!! info "" 267 | 268 | **`openplzapi.org/de/Streets?name={streetName}&postalCode={postalCode}&locality={localityName}`** 269 | 270 | : Searches for all streets matching the street name and/or postal code and/or locality name. The parameters `name`, `postalCode`, and `locality` can be used together or independently. All three parameters support [regular expressions](regex.md). The query is subject to [paging](paging.md). 271 | 272 | **`openplzapi.org/de/FullTextSearch?searchTerm={searchTerm}`** 273 | 274 | : Searches for streets using [full-text search](fulltextsearch.md) across street name, postal code, and locality name. The query is subject to [paging](paging.md). 275 | 276 | For each street, the following attributes are provided: 277 | 278 | + `name (string)`: Name of the street 279 | + `postalcode (string)`: Postal code of the locality 280 | + `locality (string)`: Name of the locality 281 | + `borough (string)`: Name of the borough or city district, if applicable 282 | + `suburb (string)`: Name of the suburb, if applicable 283 | + `municipality.key (string)`: Regional code of the municipality (8-digit) 284 | + `municipality.name (string)`: Name of the municipality 285 | + `district.key (string)`: Regional code of the district (5-digit) 286 | + `district.name (string)`: Name of the district 287 | + `governmentRegion.key (string)`: Regional code of the government region (3-digit) 288 | + `governmentRegion.name (string)`: Name of the government region 289 | + `federalState.key (string)`: State code (2-digit) 290 | + `federalState.name (string)`: Name of the federal state 291 | 292 | Example request for the street *Grabbeallee* (unique in Berlin): 293 | 294 | ``` 295 | GET https://openplzapi.org/de/Streets?name=Grabbeallee 296 | ``` 297 | 298 | Example request for all streets in Berlin starting with *G* and ending with *allee*. The regular expression `^G.*allee$` is [URL-encoded](url-encoding.md): 299 | 300 | ``` 301 | GET https://openplzapi.org/de/Streets?name=%5EG.*allee%24&locality=Berlin 302 | ``` 303 | 304 | Example full-text search with the term `Berlin Pariser Platz`. The search term is [URL-encoded](url-encoding.md): 305 | 306 | ``` 307 | GET https://openplzapi.org/de/FullTextSearch?searchTerm=Berlin%20Pariser%20Platz 308 | ``` -------------------------------------------------------------------------------- /en/docs/index.md: -------------------------------------------------------------------------------- 1 | **OpenPLZ API** is a [open data project](https://opendatahandbook.org/guide/de/what-is-open-data/) that makes a public street and postal code directory for Austria, Germany, Liechtenstein and Switzerland available via an open REST API interface. The following data can be retrieved: 2 | 3 | **:flag_at: Austria:** 4 | 5 | + Street name 6 | + Postal code and locality 7 | + Municipality (including details of district and federal province) 8 | 9 | **:flag_de: Germany:** 10 | 11 | + Street name 12 | + Postal code and locality 13 | + Municipality (including details of district, government region and federal state) 14 | 15 | **:flag_li: Liechtenstein:** 16 | 17 | + Street name 18 | + Postal code and locality 19 | + Municipality 20 | 21 | **:flag_ch: Switzerland:** 22 | 23 | + Street name 24 | + Postal code and locality 25 | + Municipality (including details of district and canton) 26 | 27 | ## Let's start 28 | 29 | The easiest way to use the API is via the command line. We will work with the command line application [curl](https://curl.se/) in this chapter. 30 | 31 | Under Linux, `curl` is usually pre-installed. Under Windows, `curl` is defined as an alias of the [Invoke-WebRequest](https://docs.microsoft.com/en-us/powershell/module/microsoft.powershell.utility/invoke-webrequest) cmdlet, so it can be used via Powershell. The command sequences used here vary slightly, so they are given separately for Powershell 7 (Windows) and Bash (Linux). 32 | 33 | ### Administrative units 34 | 35 | Subnational administrative units (e.g. federal states, Swiss cantons, districts or municipalities) can be queried per country. The basis for filtering is always the official key of the administrative unit. 36 | 37 | Here is an example request for the list of German federal states: 38 | 39 | === "Powershell 7" 40 | 41 | ``` powershell 42 | curl -X GET 'https://openplzapi.org/de/FederalStates' -H 'accept: text/json' | ConvertFrom-Json | ConvertTo-Json 43 | ``` 44 | 45 | === "Bash" 46 | 47 | ``` bash 48 | curl -X GET 'https://openplzapi.org/de/FederalStates' -H 'accept: text/json' | json_pp 49 | ``` 50 | 51 | Here is an example request for the list of all Austrian municipalities in the federal province of *Niederösterreich* (key "3"): 52 | 53 | === "Powershell 7" 54 | 55 | ``` powershell 56 | curl -X GET 'https://openplzapi.org/at/FederalProvinces/3/Municipalities' -H 'accept: text/json' | ConvertFrom-Json | ConvertTo-Json 57 | ``` 58 | 59 | === "Bash" 60 | 61 | ``` bash 62 | curl -X GET 'https://openplzapi.org/at/FederalProvinces/3/Municipalities' -H 'accept: text/json' | json_pp 63 | ``` 64 | 65 | Here is an example request for the list of all Swiss districts in the canton of *Aargau* (key "19"): 66 | 67 | === "Powershell 7" 68 | 69 | ``` powershell 70 | curl -X GET 'https://openplzapi.org/ch/Cantons/19/Districts' -H 'accept: text/json' | ConvertFrom-Json | ConvertTo-Json 71 | ``` 72 | 73 | === "Bash" 74 | 75 | ``` bash 76 | curl -X GET 'https://openplzapi.org/ch/Cantons/19/Districts' -H 'accept: text/json' | json_pp 77 | ``` 78 | 79 | Most queries for administrative units are subject to [Paging](paging.md), i.e. the result is returned in addressable data blocks. By default, only the first block or the first page with a maximum of 50 localities is returned. However, this can be influenced by specifying the optional parameters `page` and `pageSize`. 80 | 81 | ### Postal codes and localities 82 | 83 | Localities can be searched by name or postal code. The search can be designed very flexibly using regular expressions. The [POSIX Regular Expressions Syntax](regex.md) is supported. 84 | 85 | Here is an example request for the German postal code *13156*: 86 | 87 | === "Powershell 7" 88 | 89 | ``` powershell 90 | curl -X GET 'https://openplzapi.org/de/Localities?postalCode=13156' -H 'accept: text/json' | ConvertFrom-Json | ConvertTo-Json 91 | ``` 92 | 93 | === "Bash" 94 | 95 | ``` bash 96 | curl -X GET 'https://openplzapi.org/de/Localities?postalCode=13156' -H 'accept: text/json' | json_pp 97 | ``` 98 | 99 | Here is an example request for all German postal codes beginning with *13*: 100 | 101 | === "Powershell 7" 102 | 103 | ``` powershell 104 | curl -X GET 'https://openplzapi.org/de/Localities?postalCode=^13' -H 'accept: text/json' | ConvertFrom-Json | ConvertTo-Json 105 | ``` 106 | 107 | === "Bash" 108 | 109 | ``` bash 110 | curl -X GET 'https://openplzapi.org/de/Localities?postalCode=^13' -H 'accept: text/json' | json_pp 111 | ``` 112 | 113 | Queries for localities are subject to [Paging](paging.md), i.e. the result is returned in addressable data blocks. By default, only the first block or the first page with a maximum of 50 localities is returned. However, this can be influenced by specifying the optional parameters `page` and `pageSize`. 114 | 115 | Here is the first example with explicit paging (second page with a maximum of 20 localities): 116 | 117 | === "Powershell 7" 118 | 119 | ``` powershell 120 | curl -X GET 'https://openplzapi.org/de/Localities?postalCode=13156&page=2&pageSize=20' -H 'accept: text/json' | ConvertFrom-Json | ConvertTo-Json 121 | ``` 122 | 123 | === "Bash" 124 | 125 | ``` bash 126 | curl -X GET 'https://openplzapi.org/de/Localities?postalCode=13156&page=2&pageSize=20' -H 'accept: text/json' | json_pp 127 | ``` 128 | 129 | ### Streets 130 | 131 | Streets can be searched by name, postal code or locality name. The search can be designed very flexibly using regular expressions. The [POSIX Regular Expressions Syntax](regex.md) is supported. 132 | 133 | Here is an example request for the German street *Grabbeallee* (exists only once in Berlin): 134 | 135 | === "Powershell 7" 136 | 137 | ``` powershell 138 | curl -X GET 'https://openplzapi.org/de/Streets?name=Grabbeallee' -H 'accept: text/json' | ConvertFrom-Json | ConvertTo-Json 139 | ``` 140 | 141 | === "Bash" 142 | 143 | ``` bash 144 | curl -X GET 'https://openplzapi.org/de/Streets?name=Grabbeallee' -H 'accept: text/json' | json_pp 145 | ``` 146 | 147 | Here is an example request for all streets in Berlin, starting with *G* and ending with *allee*. The regular expression `^G.*allee$` is [URL encoded](url-encoding.md): 148 | 149 | === "Powershell 7" 150 | 151 | ``` powershell 152 | curl -X GET 'https://openplzapi.org/de/Streets?name=%5EG.*allee%24&locality=Berlin' -H 'accept: text/json' | ConvertFrom-Json | ConvertTo-Json 153 | ``` 154 | 155 | === "Bash" 156 | 157 | ``` bash 158 | curl -X GET 'https://openplzapi.org/de/Streets?name=%5EG.*allee%24&locality=Berlin' -H 'accept: text/json' | json_pp 159 | ``` 160 | 161 | Queries for streets are subject to [Paging](paging.md), i.e. the result is returned in addressable data blocks. By default, only the first block or the first page with a maximum of 50 streets is returned. However, this can be influenced by specifying the optional parameters `page` and `pageSize`. 162 | 163 | Here is the first example with explicit paging (second page with a maximum of 20 streets): 164 | 165 | === "Powershell 7" 166 | 167 | ``` powershell 168 | curl -X GET 'https://openplzapi.org/de/Streets?name=Grabbeallee&page=2&pageSize=20' -H 'accept: text/json' | ConvertFrom-Json | ConvertTo-Json 169 | ``` 170 | 171 | === "Bash" 172 | 173 | ``` bash 174 | curl -X GET 'https://openplzapi.org/de/Streets?name=Grabbeallee&page=2&pageSize=20' -H 'accept: text/json' | json_pp 175 | ``` 176 | 177 | ### Full-text search 178 | 179 | A [full-text search](fulltextsearch.md) can be carried out for each country using the street name, postcode and location name. 180 | 181 | Here is a full-text search for Germany with the search term `Berlin, Pariser Platz`. The search term is [URL-encoded](url-encoding.md): 182 | 183 | === "powershell 7" 184 | 185 | ``` powershell 186 | curl -X GET ‘https://localhost:44365/de/FullTextSearch?searchTerm=Berlin%2C%20Pariser%20Platz’ -H ‘accept: text/json’ | ConvertFrom-Json | ConvertTo-Json 187 | ``` 188 | 189 | === "Bash" 190 | 191 | ``` bash 192 | curl -X GET ‘https://localhost:44365/de/FullTextSearch?searchTerm=Berlin%2C%20Pariser%20Platz’ -H ‘accept: text/json’ | json_pp 193 | ``` 194 | 195 | Here is a full-text search for Liechtenstein with the search term `9490 Alte Landstrasse`. The search term is [URL-encoded](url-encoding.md): 196 | 197 | === "Powershell 7" 198 | 199 | ``` powershell 200 | curl -X GET ‘https://localhost:44365/li/FullTextSearch?searchTerm=9490%20Alte%20Landstrasse’ -H ‘accept: text/json’ | ConvertFrom-Json | ConvertTo-Json 201 | ``` 202 | 203 | === "Bash" 204 | 205 | ``` bash 206 | curl -X GET ‘https://localhost:44365/li/FullTextSearch?searchTerm=9490%20Alte%20Landstrasse’ -H ‘accept: text/json’ | json_pp 207 | ``` 208 | 209 | The full-text search is subject subject to [Paging](paging.md), i.e. the result is returned in addressable data blocks. By default, only the first block or the first page with a maximum of 50 streets is returned. However, this can be influenced by specifying the optional parameters `page` and `pageSize`. 210 | 211 | ## Tips and tricks 212 | 213 | To write the screen output of curl to a file, the parameter -o can be used. The following example saves all Swiss cantons into a JSON-formatted text file. 214 | 215 | === "Powershell 7" 216 | 217 | ``` powershell 218 | curl -X GET 'https://openplzapi.org/ch/Cantons' -H 'accept: text/json' -o 'cantons.json' 219 | ``` 220 | 221 | === "Bash" 222 | 223 | ``` bash 224 | curl -X GET 'https://openplzapi.org/ch/Cantons' -H 'accept: text/json' -o 'cantons.json' 225 | ``` 226 | 227 | -------------------------------------------------------------------------------- /en/docs/libraries.md: -------------------------------------------------------------------------------- 1 | The OpenPLZ API can be accessed directly via HTTP calls. However, it is more elegant, where available, to use a client library. 2 | 3 | The following libraries are available: 4 | 5 | ## .NET 6 | 7 | - [openpotato/openplzapi-client.net](https://github.com/openpotato/openplzapi-client.net): Official OpenPLZ API [.NET](https://dotnet.microsoft.com/) client library. 8 | 9 | ## Python 10 | 11 | - [openpotato/openplzapi-client.py](https://github.com/openpotato/openplzapi-client.py): Official OpenPLZ API [Python](https://www.python.org/) client library. 12 | 13 | ## PHP 14 | 15 | - [openpotato/openplzapi-client.php](https://github.com/openpotato/openplzapi-client.php): Official OpenPLZ API [PHP](https://www.php.net/) client library. 16 | 17 | ## Delphi 18 | 19 | - [openpotato/openplzapi-client.delphi](https://github.com/openpotato/openplzapi-client.delphi): Official OpenPLZ API [Delphi](https://www.embarcadero.com/products/delphi) client library. 20 | -------------------------------------------------------------------------------- /en/docs/liechtenstein.md: -------------------------------------------------------------------------------- 1 | The OpenPLZ API data directory for [Liechtenstein](https://en.wikipedia.org/wiki/Liechtenstein) includes street names, postal codes, localities, and administrative divisions (municipalities). 2 | 3 | ## Administrative Structure 4 | 5 | Liechtenstein's administrative structure is straightforward, reflecting the small size of the state. It consists of a few, manageable levels, centrally organised. 6 | 7 | **Principality (Fürstentum)** 8 | 9 | : The state of Liechtenstein as the highest administrative unit and sovereign entity. Liechtenstein is a constitutional hereditary monarchy based on democratic and parliamentary principles. The state is governed by the Prince and the government. 10 | 11 | **Municipalities (Gemeinden)** 12 | 13 | : The only subordinate administrative level, consisting of 11 municipalities. Municipalities are responsible for local administration and have competencies in areas such as construction and infrastructure. Each municipality is represented by a municipal council and a mayor. 14 | 15 | **Regions (historical context)** 16 | 17 | : Informal groupings of municipalities that do not constitute an official administrative level. Traditionally, Liechtenstein is divided into two historical regions—Oberland and Unterland—which hold no administrative significance. 18 | 19 | ## Requesting Municipalities 20 | 21 | The 11 municipalities of Liechtenstein can be queried through the following API endpoint: 22 | 23 | !!! info "" 24 | 25 | **`openplzapi.org/li/Communes`** 26 | 27 | : List of all municipalities in Liechtenstein. 28 | 29 | For each municipality, the following attributes are provided: 30 | 31 | + `key (string)`: Municipality number (4-digit) 32 | + `name (string)`: Official name of the municipality 33 | + `electoralDistrict (string)`: Name of the electoral district. Possible values: 34 | + `Oberland` 35 | + `Unterland` 36 | 37 | Example request for all municipalities: 38 | 39 | ``` 40 | GET https://openplzapi.org/li/Communes 41 | ``` 42 | 43 | ## Requesting Postal Codes and Localities 44 | 45 | Postal codes and localities can be queried through the following API endpoint: 46 | 47 | !!! info "" 48 | 49 | **`openplzapi.org/li/Localities?postalCode={postal code}&name={locality name}`** 50 | 51 | : Searches for all localities matching the postal code and/or locality name. The parameters `postalCode` and `name` can be used together or independently. Both parameters support [regular expressions](regex.md). The query is subject to [paging](paging.md). 52 | 53 | For each locality, the following attributes are provided: 54 | 55 | + `name (string)`: Name of the locality 56 | + `postalcode (string)`: Postal code of the locality 57 | + `commune.key (string)`: Municipality number (4-digit) 58 | + `commune.name (string)`: Official name of the municipality 59 | 60 | Example request for postal code *9490*: 61 | 62 | ``` 63 | GET https://openplzapi.org/li/Localities?postalCode=9490 64 | ``` 65 | 66 | Example request for all postal codes starting with *94*. The [regular expression](regex.md) `^94` is [URL-encoded](url-encoding.md): 67 | 68 | ``` 69 | GET https://openplzapi.org/li/Localities?postalCode=%5E94 70 | ``` 71 | 72 | ## Requesting Streets 73 | 74 | Streets can be queried through the following API endpoints: 75 | 76 | !!! info "" 77 | 78 | **`openplzapi.org/li/Streets?name={street name}&postalCode={postal code}&locality={locality name}`** 79 | 80 | : Searches for all streets matching the street name and/or postal code and/or locality name. The parameters `name`, `postalCode`, and `locality` can be used together or independently. All three parameters support [regular expressions](regex.md). The query is subject to [paging](paging.md). 81 | 82 | **`openplzapi.org/li/FullTextSearch?searchTerm={search term}`** 83 | 84 | : Searches for streets using [full-text search](fulltextsearch.md) across street name, postal code, and locality name. The query is subject to [paging](paging.md). 85 | 86 | For each street, the following attributes are provided: 87 | 88 | + `key (string)`: Street key 89 | + `name (string)`: Name of the street 90 | + `status (string)`: Street status. Possible values: 91 | + `Planned` 92 | + `Real` 93 | + `Outdated` 94 | + `postalcode (string)`: Postal code of the locality 95 | + `locality (string)`: Name of the locality 96 | + `commune.key (string)`: Municipality number (4-digit) 97 | + `commune.name (string)`: Official name of the municipality 98 | 99 | Example request for the street *Alte Landstrasse*: 100 | 101 | ``` 102 | GET https://openplzapi.org/li/Streets?name=Alte%20Landstrasse 103 | ``` 104 | 105 | Example request for all streets in Vaduz starting with *Alte* and ending with *strasse*. The [regular expression](regex.md) `^Alte.*strasse$` is [URL-encoded](url-encoding.md): 106 | 107 | ``` 108 | GET https://openplzapi.org/li/Streets?name=%5EAlte.%2Astrasse%24&locality=Vaduz 109 | ``` 110 | 111 | Example full-text search with the term `Vaduz Alte Landstrasse`. The search term is [URL-encoded](url-encoding.md): 112 | 113 | ``` 114 | GET https://openplzapi.org/li/FullTextSearch?searchTerm=Vaduz%20Alte%20Landstrasse 115 | ``` -------------------------------------------------------------------------------- /en/docs/paging.md: -------------------------------------------------------------------------------- 1 | # Paging 2 | 3 | Most API endpoints in the OpenPLZ API project implement the so-called **Paging**. 4 | 5 | ## What is paging? 6 | 7 | Paging in web services is a technique to divide the results of large amounts of data into smaller, manageable parts. Instead of sending all the results of a query at once, the content is divided into pages so that a client can access different pages sequentially or on demand. 8 | 9 | ## Why paging? 10 | 11 | Let's start with an example. The following request: 12 | 13 | ``` 14 | GET https://openplzapi.org/de/Streets?locality=Berlin 15 | ``` 16 | 17 | would return 15335 streets without paging. This is quite a lot and would place a disproportionate load on the server, increase network latency and lengthen response times. It is better to transfer this data in instalments, in so-called pages. You can configure the size of the the page, when you call it up. 18 | 19 | ## How exactly does paging work? 20 | 21 | Paging is configured using special URL parameters in the API call. This specifies which page of results the client wants to see and how many results should be displayed per page. The URL parameters are called: 22 | 23 | 1. `page`: The index of the page that is requested. 24 | 2. `pageSize`: The number of elements per page. 25 | 26 | This request returns the first 10 addresses for Berlin: 27 | 28 | ``` 29 | GET https://openplzapi.org/de/Streets?locality=Berlin&page=1&pageSize=10 30 | ``` 31 | 32 | The next request returns the following 10 addresses for Berlin: 33 | 34 | ``` 35 | GET https://openplzapi.org/de/Streets?locality=Berlin&page=2&pageSize=10 36 | ``` 37 | 38 | If the URL parameter `page` is omitted from the request, the default value `page=1` applies. If the URL parameter `pageSize` is omitted from the request, the default value `pageSize=50` applies. The request 39 | 40 | ``` 41 | GET https://openplzapi.org/de/Streets?locality=Berlin 42 | ``` 43 | 44 | therefore corresponds to the request 45 | 46 | ``` 47 | GET https://openplzapi.org/de/Streets?locality=Berlin&page=1&pageSize=50 48 | ``` 49 | 50 | The maximum size for a page is 50. 51 | 52 | ## How do I know how many pages there are? 53 | 54 | If an API request responds successfully, additional information is supplied in the [HTTP response headers](https://developer.mozilla.org/docs/Web/HTTP/Headers). Let's take a look at a typical response header list: 55 | 56 | ``` 57 | content-security-policy: default-src https: data: ‘unsafe-inline’ 58 | content-type: text/json; charset=utf-8 59 | date: Thu,26 Sep 2024 09:26:48 GMT 60 | permissions-policy: accelerometer=(),camera=(),geolocation=(),gyroscope=(),magnetometer=(),microphone=(),payment=(),usb=(),interest-cohort=() 61 | referrer-policy: strict-origin-when-cross-origin 62 | server: nginx 63 | strict-transport-security: max-age=2592000 64 | x-content-type-options: nosniff 65 | x-frame-options: SAMEORIGIN 66 | x-page: 1 67 | x-page-size: 10 68 | x-total-count: 15335 69 | x-total-pages: 1534 70 | ``` 71 | 72 | The last four values are of interest to us here: 73 | 74 | 1. `x-page`: The index of the page that was requested. 75 | 2. `x-page-size`: The number of elements per page. 76 | 3. `x-total-count`: The total number of elements for this request. 77 | 4. `x-total-pages`: The number of pages for this request. 78 | 79 | These values are returned for all API endpoints that implement paging. 80 | 81 | !!! note "Why not in the JSON payload?" 82 | 83 | The OpenPLZ API returns the paging metadata in the HTTP response headers. There are other implementations that return this information as part of the JSON payload that represents the actual response. We have decided against this because we support not only JSON but also CSV as a payload format. 84 | 85 | ## API endpoints without paging 86 | 87 | Some API endpoints do not implement paging, as the resulting data volume is manageable: 88 | 89 | + `at/FederalProvinces` 90 | + `ch/Cantons` 91 | + `de/FederalStates` 92 | + `li/Communes` 93 | 94 | -------------------------------------------------------------------------------- /en/docs/regex.md: -------------------------------------------------------------------------------- 1 | # Regular Expressions 2 | 3 | In the OpenPLZ API, search entries for street names, postcodes or place names can optionally be defined using **regular expressions**. The OpenPLZ API supports POSIX base regular expressions (BRE). 4 | 5 | ## What are regular expressions? 6 | 7 | Regular expressions (often abbreviated as regex) are a text search tool. They make it possible to search for and find specific patterns in character strings. Regular expressions can be used to perform complex search operations by specifying the type of characters or text structures to be searched for. 8 | 9 | ## POSIX Basic Regular Expressions 10 | 11 | [POSIX Basic Regular Expressions (BRE)](https://pubs.opengroup.org/onlinepubs/9799919799/) are the more traditional form of regular expressions used in Unix-like operating systems. They provide a robust and efficient way to search, match and manipulate strings. In contrast to extended regular expressions (ERE), many special characters in BRE must be escaped with a backslash (`\`) to take on their special meanings. This leads to some syntactic differences between BRE and other forms of regular expressions. 12 | 13 | BRE syntax is relatively minimalist, with several metacharacters and constructs to define matching rules. The basic components of BRE syntax are discussed below. 14 | 15 | ### Literal characters 16 | 17 | A literal character is simply a character that matches itself. Most characters are treated as literal characters unless they are metacharacters (e.g. `*`, `.`, `^`) that have special meanings. To find a literal meta character, you must escape it with a backslash (`\`). 18 | 19 | Example: 20 | 21 | + `abc` matches the character string "abc" exactly. 22 | 23 | ### Meta characters and special characters in BRE 24 | 25 |

Start anchor of a line

26 | 27 | The caret symbol `^` is used to match the start of a line or character string. 28 | 29 | Example: 30 | 31 | + `^abc` only matches "abc" if it is at the start of a line. 32 | 33 |

End of a line

34 | 35 | The dollar sign `$` matches the end of a line or string. 36 | 37 | Example: 38 | 39 | + `abc$` only matches "abc" if it is at the end of a line. 40 | 41 |

Matches any character

42 | 43 | The full stop `.` is used to match any character except the line break. 44 | 45 | Example: 46 | 47 | + `a.c` matches any three-character string beginning with "a" and ending with "c", with any character in between (e.g. "abc", "a5c"). 48 | 49 |

Null or more repetitions

50 | 51 | The asterisk `*` matches the previous element zero or more times. 52 | 53 | Example: 54 | 55 | + `ab*c` matches "ac", "abc", "abbc", "abbbc" etc. 56 | 57 |

Matches a character from a set

58 | 59 | Parenthesis expressions `[]` (also known as character classes) allow you to define a set of characters that you want to match at a specific position in the string. 60 | 61 | Examples: 62 | 63 | + `[abc]` matches "a", "b" or "c". 64 | + `[0-9]` matches any digit between 0 and 9. 65 | 66 | Special cases for expressions in brackets: 67 | 68 | + A caret (`^`) at the beginning of a parenthesis expression negates the character selection, meaning that it matches any character except those listed. 69 | 70 | Example: 71 | 72 | + `[^abc]` matches any character except "a", "b" or "c". 73 | 74 | + A hyphen (`-`) can be used to specify a range of characters. 75 | 76 | Example: 77 | 78 | + `[a-z]` matches any lowercase letter. 79 | 80 |

Masking characters

81 | 82 | In BRE, meta characters such as `*`, `.`, `^` and `$` lose their special meanings if they are escaped with a backslash `\`. 83 | 84 | Examples: 85 | 86 | + `\*` matches a literal asterisk. 87 | + `\\` matches a literal backslash. 88 | 89 | ### Repetition operators 90 | 91 |

Exactly match `m` occurrences

92 | 93 | `\{m\}` matches exactly `m` occurrences of the previous element. 94 | 95 | Example: 96 | 97 | + `a\{3\}` matches exactly three occurrences of "a" (i.e. "aaa"). 98 | 99 |

Match between `m` and `n` occurrences

100 | 101 | `\{m,n\}` matches between `m` and `n` occurrences of the previous element. 102 | 103 | Example: 104 | 105 | + `a\{2,4\}` matches between two and four occurrences of "a" (i.e. "aa", "aaa" or "aaaa"). 106 | 107 |

Match at least `m` occurrences

108 | 109 | `\{m,\}` matches `m` or more occurrences of the previous element. 110 | 111 | Example: 112 | 113 | + `a\{2,\}` matches at least two occurrences of "a" (i.e. "aa", "aaa", "aaaa" etc.). 114 | 115 | ### Grouping and back-references 116 | 117 |

Grouping

118 | 119 | Brackets `\(` and `\)` are used to group parts of the pattern. The grouped part of the pattern is treated as a single element. 120 | 121 | Example: 122 | 123 | + `\(ab\)*` matches zero or more occurrences of "ab". 124 | 125 |

Back reference

126 | 127 | A backreference refers to a previously grouped sub-expression. In BRE, backreferences are represented by `\n`, where `n` is a number representing the `n`th group in the pattern. The backreference matches the same text as the corresponding group. 128 | 129 | Example: 130 | 131 | + `\(abc\)\1` matches "abcabc", as `\1` refers to the first grouped expression "abc". 132 | 133 | ### Anchors 134 | 135 | Anchors in BRE are used to match positions and not characters. 136 | 137 | + `^`: Matches the beginning of a line. 138 | + `$`: Matches the end of a line. 139 | 140 | ### Masked meta characters 141 | 142 | Some of the metacharacters in BRE must be escaped, which is different from other regular expression syntaxes. For example: 143 | 144 | + `\{` and `\}` must be escaped to represent repetitions. 145 | + Brackets `\(` and `\)` are used for grouping. 146 | 147 | ### Examples 148 | 149 | Here are some examples to demonstrate how BRE works in practice: 150 | 151 |

Date format

152 | 153 | Muster: `\([0-9]\{2\}\)\([0-9]\{2\}\)\([0-9]\{4\}\)` 154 | 155 | This pattern matches a date format where: 156 | 157 | + The first two digits represent the day. 158 | + The second two digits represent the month. 159 | + The last four digits represent the year. 160 | 161 | Example of a match: "25092024" (stands for 25 September 2024). 162 | 163 |

Phone number

164 | 165 | Muster: `\([0-9]\{3\}\)-[0-9]\{3\}-[0-9]\{4\}` 166 | 167 | This pattern matches a phone number in the format `XXX-XXX-XXXX`, where `X` is a digit. 168 | 169 | Example of a match: "123-456-7890". 170 | 171 |

Repeated words

172 | 173 | Pattern: `\(word\)\1` 174 | 175 | This pattern matches the word "word" repeated twice in a row, e.g. "wordword". 176 | -------------------------------------------------------------------------------- /en/docs/sources.md: -------------------------------------------------------------------------------- 1 | The data basis for **OpenPLZ API** is completely based on public sources of the countries as well as on data of the [OpenStreetMap project](https://www.openstreetmap.de/). The sources are listed in detail below. 2 | 3 | ## Germany 4 | 5 | ### Municipality directory 6 | 7 | The [Federal Statistical Office (Destatis)](https://www.destatis.de) provides the *Gemeindeleitdatei GV100* for download. This file contains information on all regional units of Germany (federal states, administrative districts, counties, associations of municipalities and municipalities). The GV100 file is a text file with a fixed record structure of 220 digits that is updated regularly. 8 | 9 | Source: 10 | 11 | + [List of Municipalities (GV-ISys)](https://www.destatis.de/EN/Themes/Countries-Regions/Regional-Statistics/OnlineListMunicipalities/_inhalt.html) 12 | 13 | ### Street directory 14 | 15 | In Germany, there is no freely accessible database to obtain all postcodes and/or street names in Germany. There are commercial services that offer such data, but they cost money and may not become Open Data. 16 | 17 | An alternative is the community-run [OpenStreetMap project](https://www.openstreetmap.org/). Every week, a new and complete copy of all data in OpenStreetMap is made available both as a compressed XML file and in [PBF format (Protocolbuffer Binary Format)](https://wiki.openstreetmap.org/wiki/PBF_Format). All info on this can be found at [Planet OSM](https://planet.openstreetmap.org). The database file is very large, so OpenPLZ API works with a regional extract for Germany. The streets are extracted with all relevant information from the OpenStreetMap data and linked with the data from the GV-ISys. The result is a CSV file that has been given its place [in the following GitHub repo](https://github.com/openpotato/openplzapi.data) and is updated regularly. 18 | 19 | Source: 20 | 21 | + [OpenStreetMap data for Germany](https://download.geofabrik.de/europe/germany.html) 22 | 23 | ## Austria 24 | 25 | ### Municipality directory 26 | 27 | The [Bundesanstalt Statistik Österreich (STATISTIK AUSTRIA)](https://www.statistik.at/en/) provides downloads for regional breakdown. 28 | 29 | Sources: 30 | 31 | + [Statistik Austria Open.data](https://data.statistik.gv.at/) 32 | + [Political districts and federal provinces (PDF)](https://www.statistik.at/verzeichnis/reglisten/polbezirke.pdf) 33 | + [Municipalities (PDF)](https://www.statistik.at/verzeichnis/reglisten/gemliste_knz.pdf) 34 | 35 | ### Street directory 36 | 37 | The [Bundesanstalt Statistik Österreich (STATISTIK AUSTRIA)](https://www.statistik.at/en/) also provides the complete street directory, updated weekly. 38 | 39 | Source: 40 | 41 | + [Street directory](https://www.statistik.at/statistik.at/strassen) 42 | 43 | ## Switzerland 44 | 45 | ### Municipal directory 46 | 47 | The [Federal Statistical Office](https://www.bfs.admin.ch/bfs/en/home.html) provides APIs and downloads for regional breakdown. 48 | 49 | Source: 50 | 51 | + [Application of the Swiss municipalities](https://www.agvchapp.bfs.admin.ch/de) 52 | 53 | ### Street directory 54 | 55 | The [Federal Office of Topography](https://www.swisstopo.admin.ch/en/home.html) provides the complete, regularly updated street directory. 56 | 57 | Source: 58 | 59 | + [Street directory](https://www.swisstopo.admin.ch/de/geodata/amtliche-verzeichnisse/strassenverzeichnis.html) 60 | 61 | ## Liechtenstein 62 | 63 | ### Municipal directory 64 | 65 | The list of municipalities is based on the Liechtenstein Municipalities Act of 20 March 1996. 66 | 67 | Sources: 68 | 69 | + [Gemeindegesetz (GemG)](https://www.gesetze.li/konso/1996076000) 70 | + [Wikipedia: Verwaltungsgliederung Liechtensteins](https://w.wiki/BEPn) 71 | 72 | ### Street directory 73 | 74 | The [Swiss Federal Office of Topography](https://www.swisstopo.admin.ch/en/home.html) also provides the complete, regularly updated street directory for Liechtenstein. 75 | 76 | Source: 77 | 78 | + [Street directory](https://www.swisstopo.admin.ch/de/geodata/amtliche-verzeichnisse/strassenverzeichnis.html) 79 | -------------------------------------------------------------------------------- /en/docs/switzerland.md: -------------------------------------------------------------------------------- 1 | The OpenPLZ API data directory for [Switzerland](https://en.wikipedia.org/wiki/Switzerland) includes street names, postal codes, localities, and administrative divisions (communes, districts, and cantons). 2 | 3 | ## Administrative Structure 4 | 5 | Switzerland's administrative structure is characterised by a strong federalist system. It is divided into three levels, each with distinct competencies and responsibilities. 6 | 7 | **Confederation (Bund)** 8 | 9 | : The highest administrative unit of the Swiss federal state. The Confederation is responsible for overarching matters such as foreign policy, national defense, and the Swiss legal system. The legislature is formed by the Federal Assembly (National Council and Council of States), and the executive branch is led by the Federal Council. 10 | 11 | **Cantons (Kantone)** 12 | 13 | : The federal units below the Confederation, consisting of 26 cantons (20 full cantons and 6 half-cantons). Each canton has its own constitution, government, parliament, and courts. Cantons have significant autonomy, particularly in education, healthcare, and policing. 14 | 15 | **Communes (Gemeinden)** 16 | 17 | : The smallest administrative units with extensive self-governing authority. There are approximately 2,000 communes in Switzerland, though the number is steadily decreasing due to mergers. Communes manage local affairs such as spatial planning, schools, and water supply. They are governed by local authorities, typically including a local council and an administrative office. 18 | 19 | ## Requesting Cantons 20 | 21 | The 26 Swiss cantons can be queried through the following API endpoint: 22 | 23 | !!! info "" 24 | 25 | **`openplzapi.org/ch/Cantons`** 26 | 27 | : List of all cantons in Switzerland. 28 | 29 | For each canton, the following attributes are provided: 30 | 31 | + `key (string)`: Bfs code of the canton (max. 2 digits) 32 | + `historicalCode (string)`: Historical code of the canton 33 | + `name (string)`: Canton name 34 | + `shortName (string)`: Canton abbreviation (2 digits) 35 | 36 | Example request for the complete list of cantons: 37 | 38 | ``` 39 | GET https://openplzapi.org/ch/Cantons 40 | ``` 41 | 42 | ## Requesting Districts 43 | 44 | Districts can be queried through the following API endpoint: 45 | 46 | !!! info "" 47 | 48 | **`openplzapi.org/ch/Cantons/{cantonKey}/Districts`** 49 | 50 | : List of all districts in a canton. The canton number (up to 2 digits) is required as a parameter. The query is subject to [paging](paging.md). 51 | 52 | For each district, the following attributes are provided: 53 | 54 | + `key (string)`: Bfs code of the district (max. 4 digits) 55 | + `historicalCode (string)`: Historical code of the district 56 | + `name (string)`: District name 57 | + `shortName (string)`: District name, short 58 | + `canton.key (string)`: Bfs code of the canton (max. 2 digits) 59 | + `canton.name (string)`: Canton name 60 | + `canton.shortName (string)`: Canton abbreviation (2 digits) 61 | 62 | Example request for districts in the canton of Fribourg (Canton Key: `10`): 63 | 64 | ``` 65 | GET https://openplzapi.org/ch/Cantons/10/Districts 66 | ``` 67 | 68 | ## Requesting Communes 69 | 70 | Communes can be queried through the following API endpoints: 71 | 72 | !!! info "" 73 | 74 | **`openplzapi.org/ch/Cantons/{cantonKey}/Communes`** 75 | 76 | : List of all communes in a canton. The canton number (up to 2 digits) is required as a parameter. The query is subject to [paging](paging.md). 77 | 78 | **`openplzapi.org/ch/Districts/{districtKey}/Communes`** 79 | 80 | : List of all communes in a district. The district number (up to 4 digits) is required as a parameter. The query is subject to [paging](paging.md). 81 | 82 | For each commune, the following attributes are provided: 83 | 84 | + `key (string)`: Bfs code of the commune (max. 4 digits) 85 | + `historicalCode (string)`: Historical code of the commune 86 | + `name (string)`: Official commune name 87 | + `shortName (string)`: Commune name, short 88 | + `district.key (string)`: Bfs code of the district (max. 4 digits) 89 | + `district.name (string)`: District name 90 | + `district.shortName (string)`: District name, short 91 | + `canton.key (string)`: Bfs code of the canton (max. 2 digits) 92 | + `canton.name (string)`: Canton name 93 | + `canton.shortName (string)`: Canton abbreviation (2 digits) 94 | 95 | Example request for communes in the canton of Fribourg (Canton Key: `10`): 96 | 97 | ``` 98 | GET https://openplzapi.org/ch/Cantons/10/Communes 99 | ``` 100 | 101 | ## Requesting Postal Codes and Localities 102 | 103 | Postal codes and localities can be queried through the following API endpoints: 104 | 105 | !!! info "" 106 | 107 | **`openplzapi.org/ch/Cantons/{cantonKey}/Localities`** 108 | 109 | : List of all localities in a canton. The canton number (up to 2 digits) is required as a parameter. The query is subject to [paging](paging.md). 110 | 111 | **`openplzapi.org/ch/Districts/{districtKey}/Localities`** 112 | 113 | : List of all localities in a district. The district number (up to 4 digits) is required as a parameter. The query is subject to [paging](paging.md). 114 | 115 | **`openplzapi.org/ch/Localities?postalCode={postalCode}&name={localityName}`** 116 | 117 | : Searches for all localities that match the postal code and/or locality name. The parameters `postalCode` and `name` can be used together or independently. Both parameters support [regular expressions](regex.md). The query is subject to [paging](paging.md). 118 | 119 | For each locality, the following attributes are provided: 120 | 121 | + `key (string)`: Locality code 122 | + `name (string)`: Locality name 123 | + `postalcode (string)`: Postal code of the locality 124 | + `commune.key (string)`: Bfs code of the commune (max. 4 digits) 125 | + `commune.name (string)`: Official commune name 126 | + `commune.shortName (string)`: Commune name, short 127 | + `district.key (string)`: Bfs code of the district (max. 4 digits) 128 | + `district.name (string)`: District name 129 | + `district.shortName (string)`: District name, short 130 | + `canton.key (string)`: Bfs code of the canton (max. 2 digits) 131 | + `canton.name (string)`: Canton name 132 | + `canton.shortName (string)`: Canton abbreviation (2 digits) 133 | 134 | Example request for postal code *8001*: 135 | 136 | ``` 137 | GET https://openplzapi.org/ch/Localities?postalCode=8001 138 | ``` 139 | 140 | Example request for all Swiss postal codes starting with *80*. The regular expression `^80` is [URL-encoded](url-encoding.md): 141 | 142 | ``` 143 | GET https://openplzapi.org/ch/Localities?postalCode=%5E80 144 | ``` 145 | 146 | ## Requesting Streets 147 | 148 | Streets can be queried through the following API endpoints: 149 | 150 | !!! info "" 151 | 152 | **`openplzapi.org/ch/Streets?name={streetName}&postalCode={postalCode}&locality={localityName}`** 153 | 154 | : Searches for all streets matching the street name and/or postal code and/or locality name. The parameters `name`, `postalCode`, and `locality` can be used together or independently. All three parameters support [regular expressions](regex.md). The query is subject to [paging](paging.md). 155 | 156 | **`openplzapi.org/ch/FullTextSearch?searchTerm={searchTerm}`** 157 | 158 | : Searches for streets using [full-text search](fulltextsearch.md) across street name, postal code, and locality name. The query is subject to [paging](paging.md). 159 | 160 | For each street, the following attributes are provided: 161 | 162 | + `key (string)`: Street key 163 | + `name (string)`: Street name 164 | + `status (string)`: Street status. Possible values: 165 | + `Planned` 166 | + `Real` 167 | + `Outdated` 168 | + `postalcode (string)`: Postal code of the locality 169 | + `locality (string)`: Locality name 170 | + `commune.key (string)`: Bfs code of the commune (max. 4 digits) 171 | + `commune.name (string)`: Official commune name 172 | + `commune.shortName (string)`: Commune name, short 173 | + `district.key (string)`: Bfs code of the district (max. 4 digits) 174 | + `district.name (string)`: District name 175 | + `district.shortName (string)`: District name, short 176 | + `canton.key (string)`: Bfs code of the canton (max. 2 digits) 177 | + `canton.name (string)`: Canton name 178 | + `canton.shortName (string)`: Canton abbreviation (2 digits) 179 | 180 | Example request for the street *Bederstrasse* (unique in Zurich): 181 | 182 | ``` 183 | GET https://openplzapi.org/ch/Streets?name=Bederstrasse 184 | ``` 185 | 186 | Example request for all streets in Zurich starting with *B* and ending with *strasse*. The regular expression `^B.*strasse$` is [URL-encoded](url-encoding.md): 187 | 188 | 189 | ``` 190 | GET https://openplzapi.org/ch/Streets?name=%5EB.*strasse%24&locality=Z%C3%BCrich 191 | ``` 192 | 193 | Example full-text search with the term `Zürich Bederstrasse`. The search term is [URL-encoded](url-encoding.md): 194 | 195 | ``` 196 | GET https://openplzapi.org/ch/FullTextSearch?searchTerm=Z%C3%BCrich%20Bederstrasse 197 | ``` -------------------------------------------------------------------------------- /en/docs/url-encoding.md: -------------------------------------------------------------------------------- 1 | # URL Encoding 2 | 3 | URLs can only contain a limited set of characters as defined in [RFC 3986](https://datatracker.ietf.org/doc/html/rfc3986). Special characters or non-ASCII characters (e.g., German umlauts) must be encoded to avoid conflicts or misinterpretation. 4 | 5 | ## What is URL Encoding? 6 | 7 | URL encoding is a method to convert special characters in a URL into a safe format. This is essential because URLs are restricted to specific characters, such as letters (`A-Z`, `a-z`), numbers (`0-9`), and a few symbols (`-`, `_`, `.`). 8 | 9 | Characters that do not meet this rule, such as spaces, `#`, or non-English letters (`ä`, `ë`, `à`), must be encoded. Other characters (e.g., `/`, `?`, `&`) have specific meanings in URLs and can only be used as encoded values in query parameters. 10 | 11 | Encoding replaces each character with a combination of: 12 | 13 | 1. A **percent sign (`%`)**. 14 | 2. Two **hexadecimal digits**, representing the ASCII or UTF-8 value of the character. 15 | 16 | For the OpenPLZ API, this primarily concerns the values and [regular expressions](regex.md) used in the URL parameters `searchTerm`, `name`, `postalCode`, and `locality`. 17 | 18 | ## Which Characters Must Be Encoded? 19 | 20 | 1. Special Characters and Spaces: 21 | 22 | + A space becomes `%20`. 23 | + `&` becomes `%26`. 24 | + `=` becomes `%3D`. 25 | + etc. 26 | 27 | 2. Non-English Letters (Umlauts, Accents, etc.): 28 | 29 | + `ä` becomes `%C3%A4`. 30 | + `ö` becomes `%C3%B6`. 31 | + `à` becomes `%C3%A0`. 32 | + `ë` becomes `%C3%AB`. 33 | + etc. 34 | 35 | 3. Other Special Symbols: 36 | 37 | + `#` becomes `%23`. 38 | + `+` becomes `%2B`. 39 | + `/` becomes `%2F`. 40 | + etc. 41 | 42 | !!! note "Spaces" 43 | 44 | A space can also be represented by a plus sign (`+`) instead of `%20`. 45 | 46 | ## Example 47 | 48 | The following OpenPLZ API example returns all streets in `München` where the postal code starts with `808`: 49 | 50 | + Original: 51 | 52 | ``` 53 | GET https://openplzapi.org/de/Streets?postalcode=^808&locality=München 54 | ``` 55 | 56 | + With URL encoding: 57 | 58 | ``` 59 | GET https://openplzapi.org/de/Streets?postalcode=%5E808&locality=M%C3%BCnchen 60 | ``` 61 | Here, the circumflex `^` in the [regular expression](regex.md) is encoded as `%5E`, and the umlaut `ü` in "München" is encoded as `%C3%BC`. 62 | 63 | ## Tool 64 | 65 | The following tool helps you to encode any value. To do this, type the text into the first text field and click on ‘Encode’. 66 | 67 | 68 | 69 | 70 | 71 | You can see the URL encoded result here: 72 | 73 | 74 | 75 | 86 | 87 | ## Encoding Tables 88 | 89 | ### Latin Characters with Accents and Diacritics 90 | 91 | Character | URL Encoding | Character | URL Encoding 92 | --------- | ------------- | --------- | ------------ 93 | À | `%C3%80` | Á | `%C3%81` 94 | Â | `%C3%82` | Ã | `%C3%83` 95 | Ä | `%C3%84` | Å | `%C3%85` 96 | Æ | `%C3%86` | Ç | `%C3%87` 97 | È | `%C3%88` | É | `%C3%89` 98 | Ê | `%C3%8A` | Ë | `%C3%8B` 99 | Ì | `%C3%8C` | Í | `%C3%8D` 100 | Î | `%C3%8E` | Ï | `%C3%8F` 101 | Ð | `%C3%90` | Ñ | `%C3%91` 102 | Ò | `%C3%92` | Ó | `%C3%93` 103 | Ô | `%C3%94` | Õ | `%C3%95` 104 | Ö | `%C3%96` | Ø | `%C3%98` 105 | Ù | `%C3%99` | Ú | `%C3%9A` 106 | Û | `%C3%9B` | Ü | `%C3%9C` 107 | Ý | `%C3%9D` | Þ | `%C3%9E` 108 | ß | `%C3%9F` | à | `%C3%A0` 109 | á | `%C3%A1` | â | `%C3%A2` 110 | ã | `%C3%A3` | ä | `%C3%A4` 111 | å | `%C3%A5` | æ | `%C3%A6` 112 | ç | `%C3%A7` | è | `%C3%A8` 113 | é | `%C3%A9` | ê | `%C3%AA` 114 | ë | `%C3%AB` | ì | `%C3%AC` 115 | í | `%C3%AD` | î | `%C3%AE` 116 | ï | `%C3%AF` | ð | `%C3%B0` 117 | ñ | `%C3%B1` | ò | `%C3%B2` 118 | ó | `%C3%B3` | ô | `%C3%B4` 119 | õ | `%C3%B5` | ö | `%C3%B6` 120 | ø | `%C3%B8` | ù | `%C3%B9` 121 | ú | `%C3%BA` | û | `%C3%BB` 122 | ü | `%C3%BC` | ý | `%C3%BD` 123 | þ | `%C3%BE` | ÿ | `%C3%BF` 124 | 125 | ### Special Characters 126 | 127 | Character | Meaning | URL Encoding 128 | --------- | ---------------------------- | ------------ 129 | Space | | `%20` 130 | ! | Exclamation mark | `%21` 131 | " | Double quotation mark | `%22` 132 | \# | Hash symbol | `%23` 133 | $ | Dollar sign | `%24` 134 | % | Percent sign | `%25` 135 | & | Ampersand | `%26` 136 | ' | Apostrophe | `%27` 137 | ( | Open parenthesis | `%28` 138 | ) | Close parenthesis | `%29` 139 | \* | Asterisk | `%2A` 140 | + | Plus sign | `%2B` 141 | , | Comma | `%2C` 142 | - | Hyphen | `%2D` 143 | . | Period | `%2E` 144 | / | Forward slash | `%2F` 145 | : | Colon | `%3A` 146 | ; | Semicolon | `%3B` 147 | < | Less-than sign | `%3C` 148 | = | Equal sign | `%3D` 149 | > | Greater-than sign | `%3E` 150 | ? | Question mark | `%3F` 151 | @ | At sign | `%40` 152 | \[ | Open square bracket | `%5B` 153 | \\ | Backslash | `%5C` 154 | ] | Close square bracket | `%5D` 155 | ^ | Caret (circumflex) | `%5E` 156 | _ | Underscore | `%5F` 157 | \` | Backtick | `%60` 158 | { | Open curly brace | `%7B` 159 | \| | Vertical bar | `%7C` 160 | } | Close curly brace | `%7D` 161 | ~ | Tilde | `%7E` 162 | -------------------------------------------------------------------------------- /en/mkdocs.yml: -------------------------------------------------------------------------------- 1 | # Project information 2 | site_name: OpenPLZ API 3 | site_description: 'Documentation of the OpenPLZ API project' 4 | site_author: 'STÜBER SYSTEMS GmbH' 5 | site_url: 'https://www.openplzapi.org/' 6 | 7 | # Copyright 8 | copyright: 9 | '© 2025 STÜBER SYSTEMS GmbH : Imprint : Privacy' 10 | 11 | # Repository 12 | repo_name: 'On GitHub' 13 | repo_url: 'https://github.com/openpotato/openplzapi.website' 14 | 15 | # Theming 16 | theme: 17 | name: material 18 | language: de 19 | features: 20 | - content.code.copy 21 | - navigation.footer 22 | - navigation.instant 23 | - search.highlight 24 | - search.share 25 | - search.suggest 26 | - toc.follow 27 | palette: 28 | - scheme: default 29 | primary: 'green' 30 | accent: 'green' 31 | toggle: 32 | icon: material/brightness-7 33 | name: Switch to dark mode 34 | - scheme: slate 35 | primary: 'green' 36 | accent: 'green' 37 | toggle: 38 | icon: material/brightness-4 39 | name: Switch to light mode 40 | font: false 41 | favicon: 'assets/logos/favicon.ico' 42 | logo: 'assets/logos/logo.svg' 43 | include_search_page: false 44 | search_index_only: true 45 | static_templates: 46 | - 404.html 47 | 48 | # Social media & multi language 49 | extra: 50 | social: 51 | - icon: fontawesome/brands/bluesky 52 | link: https://bsky.app/profile/openpotato.org 53 | - icon: fontawesome/brands/mastodon 54 | link: https://fosstodon.org/@openpotato 55 | alternate: 56 | - name: Deutsch 57 | link: /de/ 58 | lang: de 59 | - name: English 60 | lang: en 61 | 62 | # Customization 63 | extra_css: 64 | - assets/css/custom.css 65 | 66 | # Plugins 67 | plugins: 68 | - search 69 | - minify: 70 | minify_html: true 71 | 72 | # Extensions 73 | markdown_extensions: 74 | - admonition 75 | - attr_list 76 | - def_list 77 | - pymdownx.emoji: 78 | emoji_index: !!python/name:material.extensions.emoji.twemoji 79 | emoji_generator: !!python/name:material.extensions.emoji.to_svg 80 | - pymdownx.superfences 81 | - pymdownx.tabbed: 82 | alternate_style: true 83 | 84 | # Navigation 85 | nav: 86 | - Welcome: index.md 87 | - Reference: 88 | - Austria: austria.md 89 | - Germany: germany.md 90 | - Liechtenstein: liechtenstein.md 91 | - Switzerland: switzerland.md 92 | - Paging: paging.md 93 | - URL Encoding: url-encoding.md 94 | - Regular Expressions: regex.md 95 | - Full Text Search: fulltextsearch.md 96 | - Error messages: errors.md 97 | - Change Log: 98 | - Data: change-log-data.md 99 | - Web Service: change-log-webservice.md 100 | - Data Sources: sources.md 101 | - Client libraries: libraries.md 102 | - Community: community.md 103 | - FAQ: faq.md 104 | - API: api.md 105 | -------------------------------------------------------------------------------- /nginx-maintenance.html: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | Maintenance 5 | 11 | 12 | 13 |

503

14 |

Temporarily Offline

15 |

The OpenPLZ API Website is currently closed for maintenance. Please check back again soon.

16 | 17 | --------------------------------------------------------------------------------