KRS API Integration Project

This project provides tools for integrating with the Polish National Court Register (Krajowy Rejestr SÄ…dowy - KRS) API and analyzing company relationships using Neo4j.

Overview

The Polish Ministry of Justice provides an open API for accessing data from the National Court Register (KRS). This project allows you to:

1. Search for companies and retrieve details from the KRS API
2. Store this data in a Neo4j graph database for relationship analysis
3. Analyze company networks, shareholders, and management relationships
4. Visualize company networks with D3.js and other formats

Key Features

• KRS API Integration: Search for organizations, get details, representatives, shareholders, etc.
• Neo4j Graph Database: Store company networks in a graph database for powerful relationship queries
• Network Analysis: Find connections between companies, common management, ownership paths
• Visualization: Export networks in various formats (D3.js HTML, JSON, GraphML)
• Command Line Interface: Access functionality from the command line
• Mock API Support: Test functionality without hitting the real API

Project Structure

krs/
├── src/ # Source code
│ ├── krs_api.py # Main API client
│ ├── krs_export.py # Export utilities
│ ├── krs_cli.py # Command line interface
│ ├── krs_http.py # HTTP client utilities
│ └── graph/ # Neo4j integration
│ ├── neo4j_connection.py # Neo4j connection
│ ├── data_model.py # Graph data model
│ ├── krs_graph_service.py # Import service
│ ├── network_analyzer.py # Network analysis
│ └── network_exporter.py # Visualization exports
│ └── mock/ # Mock API for testing
├── examples/ # Example usage
├── output/ # Output files (generated)
└── tests/ # Tests

Installation

Prerequisites

• Python 3.8+
• Neo4j Database (local or cloud)
• Required packages:

  requests
  python-dotenv
  neo4j
  

Setup

1. Clone the repository:

   git clone https://github.com/your-username/krs-api.git
   cd krs-api

2. Create a virtual environment:

   python -m venv venv
   source venv/bin/activate # On Windows: venv\Scripts\activate

3. Install dependencies:

   pip install -r requirements.txt

4. Configure environment variables:

   • Copy .env.example to .env
   • Update the Neo4j connection parameters:

     NEO4J_URI=bolt://localhost:7687
     NEO4J_USER=neo4j
     NEO4J_PASSWORD=your_password
     NEO4J_DATABASE=krsgraph
     

Usage

Basic API Usage

fromkrs_apiimportKrsAPI# Initialize the API clientapi=KrsAPI()
# Search for an entity by KRS numberresults=api.search_entity(krs_number="0000010078")
# Get detailed data about an entityentity_data=api.get_entity_details(krs_number="0000010078")
# Get representativesrepresentatives=api.get_entity_representatives(krs_number="0000010078")

Neo4j Integration

fromgraph.neo4j_connectionimportNeo4jConnectionfromgraph.krs_graph_serviceimportKRSGraphServicefromkrs_apiimportKrsAPI# Initialize connectionsneo4j=Neo4jConnection()
krs_api=KrsAPI()
# Create import servicegraph_service=KRSGraphService(neo4j, krs_api)
# Import a company and its networkgraph_service.import_company("0000010078")
graph_service.import_company_network("0000010078", depth=2)

Network Analysis

fromgraph.neo4j_connectionimportNeo4jConnectionfromgraph.network_analyzerimportCompanyNetworkAnalyzer# Initialize analyzerneo4j=Neo4jConnection()
analyzer=CompanyNetworkAnalyzer(neo4j)
# Find direct connectionsconnections=analyzer.find_direct_connections("0000010078")
# Find influential peopleinfluencers=analyzer.find_influential_people(min_companies=2)
# Find ownership pathspaths=analyzer.find_ownership_path("0000010078", "0000429681")

Network Visualization

fromgraph.neo4j_connectionimportNeo4jConnectionfromgraph.network_analyzerimportCompanyNetworkAnalyzerfromgraph.network_exporterimportNetworkExporter# Initialize exporterneo4j=Neo4jConnection()
analyzer=CompanyNetworkAnalyzer(neo4j)
exporter=NetworkExporter(analyzer)
# Export in various formatsexporter.export_network_d3js("0000010078", depth=2, output_file="network.html")
exporter.export_network_json("0000010078", depth=2, output_file="network.json")
exporter.export_network_graphml("0000010078", depth=2, output_file="network.graphml")

Command Line Interface

# Search for a company by name
python src/krs_cli.py search --name "Cyfrowy Polsat"# Get details about a company by KRS number
python src/krs_cli.py details --krs 0000010078
# Import a company into Neo4j
python src/krs_cli.py import --krs 0000010078
# Export a company network
python src/krs_cli.py network --krs 0000010078 --depth 2 --export html --output network.html

Example Scripts

The examples directory contains example scripts demonstrating how to use the API:

# Run the Cyfrowy Polsat example
python examples/cyfrowy_polsat_example.py
# Run the Neo4j integration example
python examples/cyfrowy_polsat_neo4j.py

Neo4j Data Model

The project uses the following Neo4j data model:

Nodes

• Company: KRS entities with properties (krs, name, nip, regon, status, etc.)
• Person: Representatives/managers with properties (first_name, last_name, etc.)
• Shareholder: Shareholders with properties (name, type, etc.)

Relationships

• MANAGES: Person to Company (with role property)
• OWNS_SHARES_IN: Shareholder to Company (with percentage property)
• SUBSIDIARY_OF: Company to Company
• AFFILIATED_WITH: Company to Company

Sample Cypher Queries

Here are some useful Cypher queries for exploring the data in Neo4j:

// View all companiesMATCH (c:Company) RETURNcLIMIT100// Find a specific companyMATCH (c:Company{krs:"0000010078"}) RETURNc// Find company representativesMATCH (c:Company{krs:"0000010078"})<-[r:MANAGES]-(p:Person) RETURNp.first_name, p.last_name, r.role// Find company shareholdersMATCH (c:Company{krs:"0000010078"})<-[r:OWNS_SHARES_IN]-(s:Shareholder)
RETURNs.name, r.percentage// Find common management between companiesMATCH (p:Person)-[:MANAGES]->(c1:Company)
MATCH (p)-[:MANAGES]->(c2:Company)
WHEREc1<>c2RETURNp.first_name, p.last_name, c1.name, c2.name

Test Data

For testing, you can use the following data for Cyfrowy Polsat S.A.:

• Name: Cyfrowy Polsat Spółka Akcyjna
• KRS: 0000010078
• NIP: 7961810732
• REGON: 670925160
• Address: ul. Ĺ���UBINOWA 4A, WARSZAWA

License

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

Disclaimer

This is an unofficial client for the KRS API. It is not affiliated with or endorsed by the Polish Ministry of Justice.