GUS icon

GUS

Consume GUS (Polish Statistics Office) API

Actions5

Overview

This node integrates with the GUS API, which is the Polish Statistics Office's service providing company data. It allows users to retrieve detailed information about companies registered in Poland using various identifiers such as NIP (Tax Identification Number), REGON, or KRS numbers. Additionally, it supports searching companies by multiple criteria and fetching full detailed reports including raw XML data.

Common scenarios where this node is beneficial include:

  • Verifying company details during onboarding or compliance checks.
  • Enriching customer or supplier databases with official company data.
  • Automating business intelligence workflows that require up-to-date company statistics.
  • Retrieving detailed legal or physical person reports for auditing or research purposes.

Practical examples:

  • Fetching company info by NIP to validate a vendor’s tax ID.
  • Searching companies located in a specific province or city.
  • Downloading a full company report in XML format for archival or further processing.

Properties

Name Meaning
Additional Options A collection of optional settings:
• Auto Login: Automatically login to the API (true/false).
• BIR Version: Select BIR API version ("1.0" or "1.1").
• Auto Solve Captcha: Use anti-captcha.com to solve captchas automatically.
• Request Timeout (seconds): Timeout for API requests (5 to 120 seconds, default 30).
• Include Raw Response: Include original raw response from GUS API as binary data (true/false).

The node supports these operations on the "company" resource:

  • Get by NIP: Input property NIP Number (string) - The Tax Identification Number to search for.
  • Get by REGON: Input property REGON Number (string) - The REGON number to search for.
  • Get by KRS: Input property KRS Number (string) - The KRS number to search for.
  • Get Full Report: Inputs:
    • REGON Number (string) - REGON number for the report.
    • Report Type (options) - Type of report to retrieve, e.g., "BIR11OsPrawna", "BIR11OsFizyczna", etc.
    • Silos ID (optional string) - Optional Silos ID for the report.
  • Search: Input property Search Criteria (fixed collection) with filters:
    • Company Name
    • Province
    • District
    • Municipality
    • City
    • Street

Output

The node outputs JSON objects containing company data retrieved from the GUS API. The structure varies depending on the operation but generally includes:

  • Company details such as name, address, identification numbers, and other official data.
  • For "Get Full Report," detailed report data is returned, sometimes including nested fields.
  • Metadata fields _meta are added to each output item indicating the operation, resource, and item index.
  • If enabled, the original raw API response can be included as a binary attachment named either gus_full_report (for full reports) or gus_raw_response (for other responses). This binary data contains the raw XML or JSON response from the API.
  • In case of captcha challenges, an error object with captcha details is returned prompting manual solving or enabling auto-solving.
  • If no data is found, a message indicating "No data found" is returned.

Dependencies

  • Requires an API key credential for authenticating with the GUS API.
  • Optionally requires an anti-captcha.com API key credential if automatic captcha solving is enabled.
  • Uses the external node-regon library to interact with the GUS API.
  • Network connectivity to the GUS API endpoints is necessary.
  • Configurable timeout settings to accommodate potentially slow API responses.

Troubleshooting

  • Network Errors: Common errors like "socket hang up", "ECONNRESET", "ETIMEDOUT", or "connect ECONNREFUSED" indicate network issues or GUS API server overload. Retrying after some time usually resolves these.
  • Captcha Required: If the API returns a captcha challenge, the node will output an error with captcha details. Users can either solve it manually or enable the auto captcha solving option with a valid anti-captcha.com API key.
  • Invalid Report Type: When fetching full reports, if the selected report type is invalid for the entity, the node tries alternative report types automatically. If none succeed, an error is thrown.
  • Timeouts: The GUS API can be slow; setting the request timeout too low may cause premature failures. Recommended minimum is 30 seconds.
  • Credential Issues: Failure to initialize the client often indicates incorrect API keys or wrong environment selection (sandbox vs production).
  • No Data Found: If no matching company is found for the given identifier or search criteria, the node returns a message indicating no data was found.

Links and References

Discussion