GUS REGON api client
npm install bir1Simple node.js client library to provide information about authorized government
administration authorities, regional authorities, government institutions and to
commercial entities. It connects to
REGON service and returns data
in JSON format. Data returned from original SOAP messages are parsed to JSON. By
default the following rules apply:
- the structure of the original SOAP messages are preserved (see original
messages in
documentation)
- keys are left intact (GUS use mix of snake_case and camelCase)
- values are converted to strings. Empty values are left as empty strings
Why BIR1 was choosen as package name? BIR1 (polish: "Baza Internetowa REGON") is
an internal name of the API service maintained by GUS.
Implementation follows good practices of modern node.js. It is ESM module
written in TypeScript with carefully crafted type definitions. Enjoy!
``bash`
npm install bir1
`js
import Bir from 'bir1'
const bir = new Bir()
console.log(await bir.search({ nip: '5261040567' }))
// output:
// {
// Regon: '012100784',
// Nip: '5260250995',
// StatusNip: '',
// Nazwa: 'ORANGE POLSKA SPÓŁKA AKCYJNA',
// Wojewodztwo: 'MAZOWIECKIE',
// Powiat: 'm. st. Warszawa',
// Gmina: 'Ochota',
// Miejscowosc: 'Warszawa',
// KodPocztowy: '02-326',
// ...
// }
`
See more examples here.
Class Bir provides access to REGON API
#### Constructor
new Bir(options?): Bir
Create a new Bir instance.
parameters:
- options?: Object - options objectoptions.key?: string
- - API key. If this is not provided, the internallyoptions.normalizeFn?: (obj: any) => any
stored public API key is used to access non-production GUS database. It allows
quick start, however non-production database contains old and anonymized data.
Providing GUS provided key connects to the production database.
- Function to modify response to a
more convenient format. Every JSON object extracted from SOAP message is
passed to this function. It should return modified object. E.g. it is possible
provide a function to to convert keys to camelCase or convert some values to
numbers.
#### Methods
login(): Promise
Login to the API (method: Zaloguj)
This method uses the key provided in the constructor to login to the API. After
successful login, the session id (sid) is stored in class instance and used in
subsequent requests.
Starting from version 3.0 calling this method is optional as it is called
automatically.
---
value(value): Promise
Get diagnostic information (method: GetValue)
parameters:
- value - value to retrieve. One of:StanDanych
-
-
-
-
-
-
---
search(query): Promise
Search (method: DaneSzukajPodmioty). Returns basic information about entity.
parameters:
- query: Object - search query param. One of:query.nip: string
- - NIP numberquery.regon: string
- - REGON numberquery.krs: string
- - KRS number
example:
`js
import Bir from 'bir1'
const bir = new Bir()
console.log(await bir.search({ nip: '5261040567' }))
`
---
report(query): Promise
Retrive report (method: DanePobierzPelnyRaport). Returns more detailed
information about entity depending on report type.
parameters:
- query: Object
- - REGON numberquery.report
- - report name. One of:PublDaneRaportFizycznaOsoba
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
example:
`js
import Bir from 'bir1'
const bir = new Bir()
console.log(
await bir.report({ regon: '012100784', report: 'PublDaneRaportPrawna' })
)
`
---
summary(query): Promise
Retrive summary report (method: DanePobierzRaportZbiorczy). Returns summary of
changes in database.
parameters:
- query: Object
- - date in format YYYY-MM-DD not earlier than week beforequery.report
- - report name. One of:BIR11NowePodmiotyPrawneOrazDzialalnosciOsFizycznych
-
-
-
-
-
-
---
logout(): Promise
Logout (method: Wyloguj)
By default this library returns data in the same format as it is returned in
orginal SOAP messages.
Take a look at the following example showing default behavior:
`js`
import Bir from 'bir1'
const bir = new Bir()
console.log(
await bir.report({
regon: '010058960',
report: 'BIR11OsPrawna',
})
)
// output:
// {
// praw_regon9: '010058960',
// praw_nip: '5220002334',
// praw_statusNip: '',
// praw_nazwa: 'POLSKIE LINIE LOTNICZE "LOT" SPÓŁKA AKCYJNA',
// praw_nazwaSkrocona: '',
// ...
// }
In above output keys have unnecessary prefix praw_. There is incosistent
casing, etc... Then in order to make it cleaner it is possible to provide a
function to normalize the response:
`js`
import Bir from 'bir1'
import { modern } from 'bir1/normalize'
const bir = new Bir({ normalizeFn: modern })
console.log(
await bir.report({
regon: '010058960',
report: 'BIR11OsPrawna',
})
)
// output:
// {
// regon: '010058960',
// nip: '5220002334',
// statusNip: undefined,
// nazwa: 'POLSKIE LINIE LOTNICZE "LOT" SPÓŁKA AKCYJNA',
// nazwaSkrocona: undefined,
// ...
// }
Currently there are two normalization functions provided:
- legacy - to preserve the old behavior. Don't use it unless want to provideundefined
backward compatibility with previous versions of the library. It does the
following:
- removes 'praw\_' prefix from keys
- lower first letter of keys
- replaces empty strings with
- - to convert to modern format in consistent way. It does thefiz_
following:
- remove prefixes from keys (e.g. , praw_, ...)regon9
- lower camel case keys
- unifies some keys (e.g. -> regon)undefined
- replaces empty strings with
Using above functions is completely optional. It is also possible to provide own
function which takes JSON object and returns modified.
Please note that starting from version 3.0 of that library the following
breaking changes were introduced:
1. the library is now pure ESM module (previously CJS)
2. the keys and values are returned 'as is' (previously they were processed)
- the keys are left intact (previously they were lowercased and a bit
trimmed)
- the empty values are now returned as empty strings (previously they were
returned as undefined`)
See further details in the source code of legacy
normalize function. This function can be used to preserve the old behavior as
shown in the example.