Sverige Postnummer API

Provides an easy way to lookup street names and street/box numbers that are located within a postal-code’s geographic location in Sweden.

Why

The only alternative I could find is paid. Another free service exists, but it doesn’t have street names and street/box numbers.

Where it could be used

This is useful if you need to provide an easy way for your users to enter their address, kind of like what Comhem.se has.

Check out this demo.

Dataset

This API uses a dataset I scraped from the search service provided by Posten.

The dataset is available in JSON or CSV for free on http://github.com/beshrkayali/sverige_postnummer

Warning

Some of thse postcodes don’t have the entire set of street names and box numbers within their area as the search page limits the number of results (~100), for example: 647 91.

The API

GET /1.0/get/(string: code)/

Returns a JSON Array of street names, street/box numbers, and city/locality in the geographic location of a single postal code.

  • URL Params

    code= 5 digit postcode [string] (required)

  • Data Params: None

  • Success Response

    • Code: 200 OK

      Content:

      [
        {
          "City/Locality": "Stockholm",
          "Postcode": "113 31",
          "Street Name": "Dalagatan",
          "Street/Box No.": "47 - 59"
        },
        {
          "City/Locality": "Stockholm",
          "Postcode": "113 31",
          "Street Name": "Hälsingegatan",
          "Street/Box No.": "21 - 51"
        }
      ]
      
  • Error Response

    • Code: 404 NOT FOUND

      Content:

      { "error" : "Postcode doesn't exist" }
      
    • Code: 400 BAD REQUEST

      Content:

      { "error": "Postcode has to be exactly 5 digits" }
      
    • Code: 429 TOO MANY REQUESTS

      Content:

      { "error": "Postcode has to be exactly 5 digits",
        "limit": "600 requests per hour" }
      
  • Rate Limiting Headers

    Header Name Description
    X-RateLimit-Limit The maximum number of requests that the consumer is permitted to make per hour.
    X-RateLimit-Remaining The number of requests remaining in the current rate limit window.
    X-RateLimit-Reset The time at which the current rate limit window resets in UTC epoch seconds.

    (This description has been shamelessly lifted from Github docs)

  • Simple Call

    1
    2
    3
    4
    5
    6
    7
    8
    $.ajax({
      url: "https://postnummerapi.se/api/1.0/get/11331",
      dataType: "json",
      type : "GET",
      success : function(r) {
        console.log(r);
      }
    });
    

Usage

curl.sh
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
~ % curl -i https://postnummerapi.se/api/1.0/get/21426/
HTTP/1.0 200 OK
Content-Type: application/json
Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: HEAD, OPTIONS, GET
Access-Control-Max-Age: 86400
Access-Control-Allow-Credentials: true
Access-Control-Allow-Headers: CONTENT-TYPE, AUTHORIZATION
X-RateLimit-Remaining: 592
X-RateLimit-Limit: 600
X-RateLimit-Reset: 1465729200
Content-Length: 827
Server:
Date:

[
  {
    "City/Locality": "Malm\u00f6",
    "Postcode": "214 26",
    "Street Name": "Bangatan",
    "Street/Box No.": "1 - 15"
  },
  {
    "City/Locality": "Malm\u00f6",
    "Postcode": "214 26",
    "Street Name": "Bangatan",
    "Street/Box No.": "2 - 18"
  },
  {
    "City/Locality": "Malm\u00f6",
    "Postcode": "214 26",
    "Street Name": "Claesgatan",
    "Street/Box No.": "1 - 17"
  },
  {
    "City/Locality": "Malm\u00f6",
    "Postcode": "214 26",
    "Street Name": "Claesgatan",
    "Street/Box No.": "2 - 18"
  },
  {
    "City/Locality": "Malm\u00f6",
    "Postcode": "214 26",
    "Street Name": "Fricksgatan",
    "Street/Box No.": "1 - 11"
  },
  {
    "City/Locality": "Malm\u00f6",
    "Postcode": "214 26",
    "Street Name": "Fricksgatan",
    "Street/Box No.": "2 - 6"
  }
]
jquery-example.js
1
2
3
4
5
6
7
8
$.ajax({
  url: "https://postnummerapi.se/api/1.0/get/43241/",
  dataType: "json",
  type : "GET",
  success : function(r) {
    console.log(r);
  }
});
python-example.py
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
import requests, json

data = json.loads(
    requests.get('https://postnummerapi.se/api/1.0/get/43241/')
)

# data
# [{u'Street/Box No.': u'1 - 33',
#   u'Street Name': u'Borgm\xe4staregatan',
#   u'City/Locality': u'Varberg',
#   u'Postcode': u'432 41'},
#  {u'Street/Box No.': u'2 - 36', u'Street Name': u'Borgm\xe4staregatan',
#   u'City/Locality': u'Varberg',
#   u'Postcode': u'432 41'},
# ...
# ]

Support

Note

This API is still experimental. Please use in situtations where it’s okay if things don’t work out all the time.

This API is free for use. However, it is rate-limited to 600 requests an hour.

If you make a one-time donation of 250 Kr . you get to whitelist an IP of your choosing.

    ____             __                                               ___    ____  ____
   / __ \____  _____/ /_____  __  ______ ___  ____ ___  ___  _____   /   |  / __ \/  _/
  / /_/ / __ \/ ___/ __/ __ \/ / / / __ `__ \/ __ `__ \/ _ \/ ___/  / /| | / /_/ // /
 / ____/ /_/ (__  ) /_/ / / / /_/ / / / / / / / / / / /  __/ /     / ___ |/ ____// /
/_/    \____/____/\__/_/ /_/\__,_/_/ /_/ /_/_/ /_/ /_/\___/_/     /_/  |_/_/   /___/