Gusex

Elixir client for Polish Business Registry Service (GUS BIR) Gusex is an Elixir library that provides access to the Polish Central Statistical Office (GUS) BIR (Baza Internetowa Regon) service. It enables developers to programmatically retrieve data about business entities from Polish registries including CEIDG, KRS, and RSPO, which are synchronised into the BIR database.

Features

Installation

If available in Hex, the package can be installed by adding gusex to your list of dependencies in mix.exs:

def deps do
    [
        {:gusex, "~> 1.0"}
    ]
end

Then run:

mix deps.get

Configuration

config :gusex,
    api_key: "your_production_api_key",
    environment: :production  # or :test

For testing, you can use the test environment:

config :gusex,
    api_key: "abcde12345abcde12345",  # Test API key
    environment: :test

although it is default if not specified and in dev or test environment.

Quick Start

# Login to the service and obtain a session (uses test environment by default; configure with valid API key for production environment)
{:ok, session} = Gusex.zaloguj()

# Search for entities by REGON (using ParametryWyszukiwania struct)
search_params = %Gusex.Types.ParametryWyszukiwania{Regon: "000331501"}
{:ok, entities} = Gusex.dane_szukaj_podmioty(search_params, session)
# or (using simple map with atom keys - error will be returned for invalid or non-atom keys)
{:ok, entities} = Gusex.dane_szukaj_podmioty(%{Regon: "000331501"}, session)

# Get detailed report for an entity
{:ok, report} = Gusex.dane_pobierz_pelny_raport("000331501", "BIR12OsPrawna", session)

# Logout
{:ok, true} = Gusex.wyloguj(session)

API Reference

Authentication

zaloguj/2

Authenticates with the BIR service and establishes a session.

# Using configured or default (for GUS test environment) credentials
{:ok, session} = Gusex.zaloguj()

# Using explicit credentials and environment (you shouldn't do this in production code)
{:ok, session} = Gusex.zaloguj("your_api_key", :production)

Returns:{:ok, %Gusex.Types.Session{}} or {:error, reason}

Entity Search

dane_szukaj_podmioty/2

Searches for business entities using various identifier types.

# Search by REGON (9 or 14 digits)
search_params = %Gusex.Types.ParametryWyszukiwania{Regon: "000331501"}
{:ok, entities} = Gusex.dane_szukaj_podmioty(search_params, session)

# Search by NIP (Tax ID)
search_params = %Gusex.Types.ParametryWyszukiwania{Nip: "5260001246"}
{:ok, entities} = Gusex.dane_szukaj_podmioty(search_params, session)

# Search by KRS (Court Register number)
search_params = %Gusex.Types.ParametryWyszukiwania{Krs: "0000028860"}
{:ok, entities} = Gusex.dane_szukaj_podmioty(search_params, session)

# Multiple search (up to 20 entities)
search_params = %Gusex.Types.ParametryWyszukiwania{
    Regony9zn: "000331501,123456789",
    Nipy: "5260001246,1234567890"
}
{:ok, entities} = Gusex.dane_szukaj_podmioty(search_params, session)

Returns:{:ok, [%Gusex.Types.Podmiot{}]} or {:error, error_data}

Detailed Reports

dane_pobierz_pelny_raport/3

Retrieves detailed information about a specific entity.

# Legal entities (companies)
{:ok, company_data} = Gusex.dane_pobierz_pelny_raport("000331501", "BIR12OsPrawna", session)

# Natural persons - general data
{:ok, person_data} = Gusex.dane_pobierz_pelny_raport("12345678901234", "BIR12OsFizycznaDaneOgolne", session)

# Natural persons - CEIDG business activity
{:ok, ceidg_data} = Gusex.dane_pobierz_pelny_raport("12345678901234", "BIR12OsFizycznaDzialalnoscCeidg", session)

# Local units of legal entities
{:ok, local_unit} = Gusex.dane_pobierz_pelny_raport("12345678901234", "BIR12JednLokalnaOsPrawnej", session)

Available Report Types:

Aggregate Reports

dane_pobierz_raport_zbiorczy/3

Retrieves aggregate reports with lists of entities modified on a specific date.

# New legal entities and individual business activities
{:ok, new_entities} = Gusex.dane_pobierz_raport_zbiorczy(
    "2014-01-15",
    "BIR11NowePodmiotyPrawneOrazDzialalnosciOsFizycznych",
    session
)

Available Aggregate Reports:

Service Information

get_value/2

Retrieves service diagnostic information.

# Get service status message (no session required)
{:ok, service_message} = Gusex.get_value("KomunikatUslugi")

# Get session status (requires active session)
{:ok, session_status} = Gusex.get_value("StatusSesji", session)

wyloguj/1

Terminates the active session.

{:ok, true} = Gusex.wyloguj(session)

Data Types and Structures

Core Types

# Session information
%Gusex.Types.Session{
    id: "abcdef1234567890abcd",
    environment: :test,
    endpoint_url: "https://wyszukiwarkaregontest.stat.gov.pl/wsBIR/UslugaBIRzewnPubl.svc"
}

# Search parameters
%Gusex.Types.ParametryWyszukiwania{
    Regon: "000331501",
    Nip: nil,
    Krs: nil,
    Regony9zn: nil,
    Regony14zn: nil,
    Nipy: nil,
    Krsy: nil
}

# Entity information
%Gusex.Types.Podmiot{
    Regon: "000331501",
    Nip: "5260001246",
    StatusNip: "",
    Nazwa: "GŁÓWNY URZĄD STATYSTYCZNY",
    Typ: "P",  # P = Legal entity, F = Natural person
    SilosID: "6"
}

Entity Types

Activity Types (SilosID)

Environment Setup

Test Environment

Production Environment

Error Handling

The library provides comprehensive error handling for various scenarios:

case Gusex.zaloguj("api_key", :production) do
    {:ok, session} ->
        # Success
        session
    {:error, :api_key_missing} ->
        # No API key provided or configured
        handle_missing_key()
    {:error, :login_failure} ->
        # Invalid credentials or service unavailable
        handle_login_failure()
    {:error, reason} ->
        # Other errors (network, parsing, etc.)
        handle_error(reason)
end

Technical Notes

Session Management

Data Security

Rate Limiting

Dependencies

Documentation

Documentation can be generated with ExDoc and published on HexDocs. Once published, the docs can be found at https://hexdocs.pm/gusex.

Contributing

  1. Fork the repository
  2. Create your feature branch (git checkout -b feature/amazing-feature)
  3. Make your changes following the existing code style (do NOT run mix format)
  4. Add tests for new functionality
  5. Run tests and ensure they pass (mix test)
  6. Run static analysis (mix credo)
  7. Commit your changes
  8. Push to the branch
  9. Open a Pull Request

License

This project is licensed under the MIT License - see the LICENCE file for details.

Support

For issues, questions, or contributions, please visit the BitBucket repository.

Note: This library provides access to official Polish government business registry data. Ensure compliance with applicable data protection regulations and service terms of use.