├── LICENSE ├── README.md └── examples ├── json-to-php.php └── xml-to-php.php /LICENSE: -------------------------------------------------------------------------------- 1 | The MIT License (MIT) 2 | 3 | Copyright (c) 2015-2020 Kennet "Nille" Nilsson 4 | 5 | Permission is hereby granted, free of charge, to any person obtaining a copy 6 | of this software and associated documentation files (the "Software"), to deal 7 | in the Software without restriction, including without limitation the rights 8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 9 | copies of the Software, and to permit persons to whom the Software is 10 | furnished to do so, subject to the following conditions: 11 | 12 | The above copyright notice and this permission notice shall be included in all 13 | copies or substantial portions of the Software. 14 | 15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 21 | SOFTWARE. 22 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | **\# DEPRECATED** 2 | 3 | This version of PAP/API is no longer active, but the API will continue working but with outdated information. New version to be announced. Meanwhile, please consider using [PAP/API Lite](https://github.com/aliasnille/papilite) instead. 4 | 5 | [![No Maintenance Intended](http://unmaintained.tech/badge.svg)](http://unmaintained.tech/) 6 | 7 | ![PAP-API - Open API that checks and verifies Swedish addresses and postal codes](https://www.papapi.se/img/papapi-main.png) 8 | 9 | # PAP-API 10 | *PAP is a abbreviation of "Postnummer - Adress - Postort" in Swedish.* 11 | 12 | **_Open API that checks and verifies Swedish addresses and postal codes._** 13 | 14 | **Note:** For more information in Swedish, please visit [www.papapi.se](https://www.papapi.se/). 15 | 16 | ## Introduction 17 | 18 | For more than 10 years I worked as a web developer and in recent years I have been working more and more with APIs of various kinds. This has created an interest in me for APIs. 19 | When the vacation were approaching, I got time to develop my own API, maybe nothing revolutionary but a moderate project for me to test and learn. 20 | My API is now finished and launched publicly. With PAP-API, you can easily retrieve data in XML, JSON or JSONP to check and verify addresses and postal codes in Sweden. 21 | 22 | ## Usage 23 | 24 | PAP-API is free to use, but abnormally high usage (more than 5,000 requests per user and day) may result in suspension. Before you can start using PAP-API, you must sign up on [https://www.papapi.se/#registration](https://www.papapi.se/#registration) with your first name, last name and e-mail address. After registration you will receive a unique "token" that you use to connect to PAP-API. 25 | 26 | **Note:** No registration details will disclosed to a third party. 27 | 28 | ### Specification 29 | 30 | Parameter|Explanation|Example 31 | ---|---|--- 32 | **z**|Postal code / zip code|`z=114+34` 33 | **s**|Street address|`s=Birger+Jarlsgatan` or `s=Birger+Jarlsgatan+10` 34 | **c**|City|`c=Stockholm` 35 | **v**|Address validation|`v=Birger+Jarlsgatan|10|114+34|Stockholm` 36 | 37 | **Note** Only the parameters `s` (street address) and `c` (city) can be combined. To address validation separate street, street number, postal code and city with `|` (vertical bar). Values may not contain any spaces, these must be replaced with `+` (plus). 38 | 39 | ### Status codes (address validation) 40 | 41 | Status code|Explanation 42 | ---|--- 43 | **100**|Correct specified address 44 | **200**|Incorrect street number for the specified address 45 | **300**|Incorrect street and/or street number for the specified address 46 | **400**|Inorrect city for the specified address 47 | **500**|Incorrect zipcode for the specified address 48 | **600**|Incorrect street number and city for the specified address 49 | **700**|Incorrect street number and zipcode for the specified address 50 | **800**|Incorrect specified address 51 | **900**|Generally error message 52 | 53 | ### Request data 54 | 55 | #### XML 56 | 57 | ##### Examples of possible requests 58 | 59 | Street address + City 60 | 61 | `https://papapi.se/xml/?s=Birger+Jarlsgatan&c=Stockholm&token=YOUR_TOKEN` 62 | 63 | Street address + Number + City 64 | 65 | `https://papapi.se/xml/?s=Birger+Jarlsgatan+10&c=Stockholm&token=YOUR_TOKEN` 66 | 67 | Street address 68 | 69 | `https://papapi.se/xml/?s=Birger+Jarlsgatan&token=YOUR_TOKEN` 70 | 71 | Street address + Number 72 | 73 | `https://papapi.se/xml/?s=Birger+Jarlsgatan+10&token=YOUR_TOKEN` 74 | 75 | Postal code 76 | 77 | `https://papapi.se/xml/?z=114+34&token=YOUR_TOKEN` 78 | 79 | City 80 | 81 | `https://papapi.se/xml/?c=Stockholm&token=YOUR_TOKEN` 82 | 83 | Address validation 84 | 85 | `https://papapi.se/xml/?v=Birger+Jarlsgatan|10|114+34|Stockholm&token=YOUR_TOKEN` 86 | 87 | #### JSON 88 | 89 | ##### Examples of possible requests 90 | 91 | Street address + City 92 | 93 | `https://papapi.se/json/?s=Birger+Jarlsgatan&c=Stockholm&token=YOUR_TOKEN` 94 | 95 | Street address + Number + City 96 | 97 | `https://papapi.se/json/?s=Birger+Jarlsgatan+10&c=Stockholm&token=YOUR_TOKEN` 98 | 99 | Street address 100 | 101 | `https://papapi.se/json/?s=Birger+Jarlsgatan&token=YOUR_TOKEN` 102 | 103 | Street address + Number 104 | 105 | `https://papapi.se/json/?s=Birger+Jarlsgatan+10&token=YOUR_TOKEN` 106 | 107 | Postal code 108 | 109 | `https://papapi.se/json/?z=114+34&token=YOUR_TOKEN` 110 | 111 | City 112 | 113 | `https://papapi.se/json/?c=Stockholm&token=YOUR_TOKEN` 114 | 115 | Address validation 116 | 117 | `https://papapi.se/json/?v=Birger+Jarlsgatan|10|114+34|Stockholm&token=YOUR_TOKEN` 118 | 119 | #### JSONP 120 | 121 | ##### Examples of possible requests 122 | 123 | Street address + City 124 | 125 | `https://papapi.se/jsonp/?s=Birger+Jarlsgatan&c=Stockholm&token=YOUR_TOKEN` 126 | 127 | Street address + Number + City 128 | 129 | `https://papapi.se/jsonp/?s=Birger+Jarlsgatan+10&c=Stockholm&callback=YOUR_CALLBACK&token=YOUR_TOKEN` 130 | 131 | Street address 132 | 133 | `https://papapi.se/jsonp/?s=Birger+Jarlsgatan&callback=YOUR_CALLBACK&token=YOUR_TOKEN` 134 | 135 | Street address + Number 136 | 137 | `https://papapi.se/jsonp/?s=Birger+Jarlsgatan+10&callback=YOUR_CALLBACK&token=YOUR_TOKEN` 138 | 139 | Postal code 140 | 141 | `https://papapi.se/jsonp/?z=114+34&callback=YOUR_CALLBACK&token=YOUR_TOKEN` 142 | 143 | City 144 | 145 | `https://papapi.se/jsonp/?c=Stockholm&callback=YOUR_CALLBACK&token=YOUR_TOKEN` 146 | 147 | Address validation 148 | 149 | `https://papapi.se/jsonp/?v=Birger+Jarlsgatan|10|114+34|Stockholm&callback=YOUR_CALLBACK&token=YOUR_TOKEN` 150 | 151 | ### Response data 152 | 153 | *Note: Max 200 rows per response.* 154 | 155 | #### XML 156 | 157 | ``` 158 | 159 | 160 | PAP-API 161 | HTTPS://WWW.PAPAPI.SE/ 162 | 1.22 163 | UTF-8 164 | 165 | 166 | BIRGER JARLSGATAN 167 | 2-14 168 | 114 34 169 | STOCKHOLM 170 | STOCKHOLM 171 | 0180 172 | STOCKHOLM 173 | 174 | 175 | ``` 176 | 177 | #### XML (address validation) 178 | 179 | ``` 180 | 181 | 182 | PAP-API 183 | HTTPS://WWW.PAPAPI.SE/ 184 | 1.22 185 | UTF-8 186 | 187 |
188 | BIRGER JARLSGATAN 189 | 10 190 | 114 34 191 | STOCKHOLM 192 |
193 | 194 | 100 195 | KORREKT ANGIVEN ADRESS 196 | CORRECT SPECIFIED ADDRESS 197 | 198 | 199 | ``` 200 | 201 | #### JSON 202 | 203 | ``` 204 | { 205 | "api":{ 206 | "name":"PAP-API", 207 | "url":"HTTPS://WWW.PAPAPI.SE/", 208 | "version":"1.22", 209 | "encoding":"UTF-8" 210 | }, 211 | "result":[ 212 | { 213 | "street":"BIRGER JARLSGATAN", 214 | "number":"2-14", 215 | "zipcode":"114 34", 216 | "city":"STOCKHOLM", 217 | "municipality":"STOCKHOLM", 218 | "code":"0180", 219 | "state":"STOCKHOLM" 220 | } 221 | ] 222 | } 223 | ``` 224 | 225 | #### JSON (address validation) 226 | 227 | ``` 228 | { 229 | "api":{ 230 | "name":"PAP-API", 231 | "url":"HTTPS://WWW.PAPAPI.SE/", 232 | "version":"1.22", 233 | "encoding":"UTF-8" 234 | }, 235 | "result":{ 236 | "address":{ 237 | "street":"BIRGER JARLSGATAN", 238 | "number":"10", 239 | "zipcode":"114 34", 240 | "city":"STOCKHOLM" 241 | }, 242 | "status":{ 243 | "code":"100", 244 | "description_sv":"KORREKT ANGIVEN ADRESS", 245 | "description_en":"CORRECT SPECIFIED ADDRESS" 246 | } 247 | } 248 | } 249 | ``` 250 | 251 | #### JSONP 252 | 253 | ``` 254 | YOUR_CALLBACK( 255 | { 256 | "api":{ 257 | "name":"PAP-API", 258 | "url":"HTTPS://WWW.PAPAPI.SE/", 259 | "version":"1.22", 260 | "encoding":"UTF-8" 261 | }, 262 | "result":[ 263 | { 264 | "street":"BIRGER JARLSGATAN", 265 | "number":"2-14", 266 | "zipcode":"114 34", 267 | "city":"STOCKHOLM", 268 | "municipality":"STOCKHOLM", 269 | "code":"0180", 270 | "state":"STOCKHOLM" 271 | } 272 | ] 273 | } 274 | ); 275 | ``` 276 | 277 | #### JSONP (address validation) 278 | 279 | ``` 280 | YOUR_CALLBACK( 281 | { 282 | "api":{ 283 | "name":"PAP-API", 284 | "url":"HTTPS://WWW.PAPAPI.SE/", 285 | "version":"1.22", 286 | "encoding":"UTF-8" 287 | }, 288 | "result":{ 289 | "address":{ 290 | "street":"BIRGER JARLSGATAN", 291 | "number":"10", 292 | "zipcode":"114 34", 293 | "city":"STOCKHOLM" 294 | }, 295 | "status":{ 296 | "code":"100", 297 | "description_sv":"KORREKT ANGIVEN ADRESS", 298 | "description_en":"CORRECT SPECIFIED ADDRESS" 299 | } 300 | } 301 | } 302 | ); 303 | ``` 304 | 305 | ### Code examples 306 | 307 | If you are looking for full code samples, you will find this in the [*example folder*](https://github.com/aliasnille/pap-api/tree/master/examples). 308 | 309 | #### XML TO PHP 310 | 311 | ```php 312 | $token = 'YOUR_TOKEN'; 313 | $url = 'https://papapi.se/xml/?s=Birger+Jarlsgatan+10&c=Stockholm&token='.$token; 314 | 315 | $ch = curl_init($url); 316 | curl_setopt_array($ch, array( 317 | CURLOPT_RETURNTRANSFER => 1, 318 | CURLOPT_URL => $url 319 | )); 320 | $response = curl_exec($ch); 321 | curl_close($ch); 322 | 323 | $xml = simplexml_load_string($response); 324 | 325 | if ($xml->item) { 326 | // SHOWS YOUR RESULT 327 | foreach($xml->item as $item) { 328 | echo '

'; 329 | echo $item->street.' '.$item->number.'
'; 330 | echo $item->zipcode.' '.$item->city.'
'; 331 | echo $item->municipality.', '.$item->state; 332 | echo '

'; 333 | } 334 | } else { 335 | // IF YOUR RESULT IS EMPTY 336 | echo 'No result!'; 337 | } 338 | ``` 339 | 340 | #### JSON TO PHP 341 | 342 | ```php 343 | $token = 'YOUR_TOKEN'; 344 | $url = 'https://papapi.se/json/?s=Birger+Jarlsgatan+10&c=Stockholm&token='.$token; 345 | 346 | $ch = curl_init($url); 347 | curl_setopt_array($ch, array( 348 | CURLOPT_RETURNTRANSFER => 1, 349 | CURLOPT_URL => $url 350 | )); 351 | $response = curl_exec($ch); 352 | curl_close($ch); 353 | 354 | $json = json_decode($response, true); 355 | 356 | if (!$json['result']['message']) { 357 | // SHOWS YOUR RESULT 358 | foreach($json['result'] as $item) { 359 | echo '

'; 360 | echo $item['street'].' '.$item['number'].'
'; 361 | echo $item['zipcode'].' '.$item['city'].'
'; 362 | echo $item['municipality'].', '.$item['state']; 363 | echo '

'; 364 | } 365 | } else { 366 | // IF YOUR RESULT IS EMPTY 367 | echo 'No result!'; 368 | } 369 | ``` 370 | 371 | ## Uptime 372 | 373 | Check uptime for PAP-API, [https://www.papapi.se/#uptime](https://www.papapi.se/#uptime). 374 | 375 | ## Updates 376 | 377 | **12/17/2017** - Regular monthly update of the database. 378 | 379 | **11/08/2017** - Regular monthly update of the database. 380 | 381 | **10/02/2017** - Regular monthly update of the database. 382 | 383 | **09/17/2017** - Regular monthly update of the database. 384 | 385 | **08/07/2017** - Regular monthly update of the database. 386 | 387 | **07/06/2017** - Regular monthly update of the database. 388 | 389 | **06/18/2017** - Some minor text and code changes in this document. Also added full code samples in the [*example folder*](https://github.com/aliasnille/pap-api/tree/master/examples). 390 | 391 | **06/05/2017** - Regular monthly update of the database. 392 | 393 | **05/16/2017** - Regular monthly update of the database. This time a major update. Version 2.0 of PAP-API will be released after the summer. 394 | 395 | **04/10/2017** - Regular monthly update of the database. 396 | 397 | **03/19/2017** - Regular monthly update of the database (major update will be released soon!). 398 | 399 | **02/06/2017** - Regular monthly update of the database. 400 | 401 | **01/02/2017** - Regular monthly update of the database. 402 | 403 | **12/07/2016** - Regular monthly update of the database. 404 | 405 | **11/08/2016** - Regular monthly update of the database. 406 | 407 | **10/03/2016** - Regular monthly update of the database. 408 | 409 | **09/13/2016** - Regular monthly update of the database. 410 | 411 | **08/10/2016** - PAP-API now supports HTTPS (HTTP will continue working). Retrieve also data in [JSONP](https://github.com/aliasnille/pap-api#jsonp) with custom callback. 412 | 413 | **08/08/2016** - Regular monthly update of the database. 414 | 415 | **07/09/2016** - Regular monthly update of the database. 416 | 417 | **06/09/2016** - Regular monthly update of the database. 418 | 419 | **05/01/2016** - Regular monthly update of the database. This time a major update. 420 | 421 | **04/06/2016** - Regular monthly update of the database. 422 | 423 | **03/13/2016** - **Address validation new feature!** Use PAP-API to easily validate addresses. Learn more about address validation in the documentation above or visit [https://www.papapi.se/](https://www.papapi.se/). Even minor updates are made. 424 | 425 | **03/06/2016** - Regular monthly update of the database. 426 | 427 | **02/07/2016** - Regular monthly update of the database. 428 | 429 | **01/03/2016** - Major update! PAP-API has moved to a new domain ([https://www.papapi.se/](https://www.papapi.se/)) and has launched a website. Please visit the website! PAP-API will continue to work on the old domain (pap.devr.se) for six months (07/03/2016). If you use PAP API, you only need to replace **pap.devr.se** with **papapi.se**. 430 | 431 | **01/01/2016** - Regular monthly update of the database. 432 | 433 | **12/15/2015** - Regular monthly update of the database. 434 | 435 | **11/17/2015** - Regular monthly update of the database. 436 | 437 | **10/08/2015** - Regular monthly update of the database. 438 | 439 | **09/03/2015** - Regular monthly update + added municipality code ("kommunkod" in Swedish) in [response data](https://github.com/aliasnille/pap-api#response-data). Decreased the number of requests from 6,000 to 5,000 per user and day. Also decreased the number of rows per result from 250 to 200. 440 | 441 | **08/22/2015** - Redesign of [registration](http://pap.devr.se/registration) and [uptime](http://pap.devr.se/uptime). 442 | 443 | **08/18/2015** - Major update of the database and optimization. The database now contains nearly 650,000 unique rows. Guarantee an accuracy of 95 % for each request. Many updates are underway. 444 | 445 | **08/07/2015** - New major update of the database. Added municipality ("kommun" in Swedish) and state ("län" in Swedish). The added data is also available in the [response data](https://github.com/aliasnille/pap-api#response-data). 446 | 447 | **08/06/2015** - Major update of the database (now more than 430,000 unique rows). 448 | 449 | **08/02/2015** - PAP-API launched. 450 | 451 | ## License 452 | 453 | This project is released under the [MIT License](https://github.com/aliasnille/pap-api/blob/master/LICENSE). 454 | 455 | **_Please report any bugs!_** 456 | -------------------------------------------------------------------------------- /examples/json-to-php.php: -------------------------------------------------------------------------------- 1 | 1, 20 | CURLOPT_URL => $url 21 | )); 22 | 23 | // Execute your request 24 | $response = curl_exec($ch); 25 | 26 | // Close cURL session 27 | curl_close($ch); 28 | 29 | // Decodes JSON into a PHP variable 30 | $json = json_decode($response, true); 31 | ?> 32 | 33 | 34 | 35 | 36 | PAP-API: Simple example for JSON 37 | 40 | 41 | 42 | 43 | '; 48 | echo $item['street'].' '.$item['number'].'
'; 49 | echo $item['zipcode'].' '.$item['city'].'
'; 50 | echo $item['municipality'].', '.$item['state']; 51 | echo '

'; 52 | } 53 | } else { 54 | // If your result is empty 55 | echo '

No result!

'; 56 | } 57 | ?> 58 | 59 | 60 | -------------------------------------------------------------------------------- /examples/xml-to-php.php: -------------------------------------------------------------------------------- 1 | 1, 20 | CURLOPT_URL => $url 21 | )); 22 | 23 | // Execute your request 24 | $response = curl_exec($ch); 25 | 26 | // Close cURL session 27 | curl_close($ch); 28 | 29 | // Convert XML into an object 30 | $xml = simplexml_load_string($response); 31 | ?> 32 | 33 | 34 | 35 | 36 | PAP-API: Simple example for XML 37 | 40 | 41 | 42 | 43 | item) { 45 | // Shows your result 46 | foreach($xml->item as $item) { 47 | echo '

'; 48 | echo $item->street.' '.$item->number.'
'; 49 | echo $item->zipcode.' '.$item->city.'
'; 50 | echo $item->municipality.', '.$item->state; 51 | echo '

'; 52 | } 53 | } else { 54 | // If your result is empty 55 | echo '

No result!

'; 56 | } 57 | ?> 58 | 59 | 60 | --------------------------------------------------------------------------------