Icelandic Post-Codes ("Póstnúmer")

Icelandic post-codes (Póstnúmer) and locality names as a JavaScript object. Also includes the dative form ("þágufall") of the locality name.

This module also contains a lookup table for Þjóðskrá's (Iceland's National Registry) "magic codes" for localities, counties, countries and continents.

npm install postnumer
yarn add postnumer
bun add postnumer

Contents:

• Postal Codes
  • postalCodes
  • postalCodeMap
• National Registry Place Codes
  • thjodskraPlaces
• Contributing
• Changelog
• Other Iceland-Themed Libraries

Postal Codes

The postal code information isf fetched from an official data-source linked to from this page: https://www.byggdastofnun.is/is/postthjonusta/postnumer

See postnumerMeta for information on when your version of the data was last updated.

import { postnumerMeta } from 'postnumer';

console.log(postnumerMeta.lastUpdated);
// "2024-02-18"

postalCodes

Type: Array<{ postcode: number, name: string, name_dative: string }>

An array containing every post-code ("póstnúmer") in Iceland, along with its corresponding place name.

Ideal for generating drop-downs, auto-completes, etc.

import { postalCodes } from 'postnumer';

const lastItem = postalCodes[postalCodesArr.length - 1];
lastItem.postcode; // 902
lastItem.name; // 'Vestmannaeyjar'
lastItem.name_dative; // 'Vestmannaeyjum'

postalCodeMap

Type: Record<number, { name: string, name_dative: string }>

Lookup table for the place names (localities) of every known post-code ("póstnúmer") in Iceland.

import { postalCodeMap } from 'postnumer';

const info = postalCodeMap[200];
info.postcode; // 200
info.name; // 'Kópavogur'
info.name_dative; // 'Kópavogi'

National Registry Place Codes

Iceland's National Registry ("Þjóðskrá") uses a set of "magic codes" to refer to localities, counties, countries and continents.

This information is sourced from Þjóðskrá's homepage: https://www.skra.is/um-okkur/utgafur-og-skjol/taknmal-thjodskrar

thjodskraPlaces

Type: Record<string|number, string>

Lookup table for Þjóðskrá's place and couuntry code values for localities, counties, countries and continents.

It's useful for translating Þjóðskrá's cryptic codes to human-readable names.

import { thjodskraPlaces } from 'postnumer';

const place1 = thjodskraPlaces['3606']; // 'Borgarnes'
const place2 = thjodskraPlaces['XT']; // 'Afríka, ótilgreint land'

NOTE: Þjóðskrá also has similar magic codes for geners, marital status, religious affiliation, etc. This module considers those codes out of scope.

Contributing

Because the (shameful) lack of public APIs, the data exported by this module has to be manually updated. Find detailed step-by-step directions at the top of postnumer.mjs and places.mjs.

Pull requests welcome, and please open an issue if you have ideas for new features or improvements.

Changelog

See CHANGELOG.md

Other Iceland-Themed Libraries

• is-kennitala - Best-of-breed kennitala (Icelandic national ID) validation and utility library.
• fridagar - Icelandic public holidays and other commonly observed 'special' days.