Address Browser is a full-stack web application forquerying hierarchical address data from Polish public services (GUGiK). The application features a Python-based backend (FastAPI), a PostgreSQL database for relational data storage, and a modern React frontend for an intuitive user experience.
- Integration with GUGiK SOAP API for hierarchical address data retrieval
- Relational database schema using PostgreSQL
- FastAPI backend exposing a REST API for querying address data
- React-based frontend with live search and filter functionality
- Modular component architecture with Vite-based development workflow
- Python 3.10 or higher
- PostgreSQL
zeep,psycopg2,requests,configparserfastapi,uvicorn
- Node.js
- npm
git clone https://github.com/your-user/address-browser.git
cd address-browser
### 2. Backend Setup
- Edit `Backend/.env` with your PostgreSQL credentials and the WSDL endpoint from GUGiK.
- Install backend dependencies:
```bash
pip install -r requirements.txt- Import address data by running:
python Backend/data_importer.py- Start the FastAPI server:
uvicorn Backend.search:app --reload --port 8000cd address-search-app
npm install
npm run devThis will launch the development server at http://localhost:5173, assuming the default Vite configuration.
Based on the source code of search.py, your FastAPI backend exposes multiple search endpoints for querying address data at different administrative levels. Here's a rewritten and professional API Overview section that accurately reflects the functionality of the project:
The backend exposes a set of RESTful endpoints via FastAPI for querying address components stored in the PostgreSQL database.
http://localhost:8000
Search for counties (powiaty) matching a query string.
Search for communes (gminy) within a given county.
Search for localities (miejscowości).
Search for streets (ulice) based on a locality.
Returns a list of all voivodeships (województwa).
Returns all counties belonging to a specific voivodeship.
Returns all communes within a specific county.
Returns all localities within a given commune.
Returns all streets within a given locality.
Returns addresses based on a specific street.
address-browser/
├── Backend/ # Backend logic and database access
│ ├── sql/ # SQL scripts and helper modules
│ │ ├── insert.py
│ │ ├── queries.py
│ │ ├── select_ID.py
│ │ ├── sequences.py
│ │ └── tables.py
│ ├── .env_example # Sample environment config file
│ ├── data_importer.py # Script for downloading and importing address data from GUGiK
│ └── search.py # FastAPI app exposing the REST API
├── address-search-app/ # Frontend application built with React + Vite
│ ├── src/ # Application source code
│ │ ├── archive/ # (Possibly unused/legacy components)
│ │ │ ├── BrowseAddress.jsx # Component for browsing hierarchical address data
│ │ │ ├── ResultsList.jsx # Component for displaying search results
│ │ │ └── SearchBar.jsx # Component for entering search queries
│ │ ├── App.jsx # Main React application component
│ │ ├── index.css # Global styles
│ │ └── main.jsx # Entry point for rendering the React app
│ ├── index.html # HTML template used by Vite
│ ├── package.json # Frontend dependencies and scripts
│ ├── postcss.config.js # PostCSS configuration
│ ├── tailwind.config.js # Tailwind CSS settings
│ └── vite.config.js # Vite development/build configuration
├── .gitignore # Git ignored files
├── README.md # Main project documentation
├── package-lock.json # npm lockfile for consistent installs
└── requirements.txt # Python backend dependencies
- The GUGiK API may occasionally be unavailable due to maintenance.
- Initial data import can take several hours due to the size and depth of the address browse.
- The importer includes basic error handling and retry logic for unstable connections.
- Ensure CORS is enabled in
search.pyif the frontend and backend are served from different origins. - Unit tests are not included in this version.
Jan Weis
GitHub: https://github.com/Weisjan