Courier Kyiv — Address Delivery Module for OpenCart

Courier Kyiv — Courier Address Delivery in Kyiv with a Street and Building Directory for OpenCart

Courier Kyiv is a courier delivery extension for OpenCart and ocStore that allows customers to select a street and building from a synchronized Kyiv address directory instead of entering the delivery address as free text.

Addresses are loaded from the Kyiv City State Administration address registry and stored in the store’s local database. This ensures that street and building suggestions work quickly and do not depend on the availability of an external API during each checkout.

Main Features

• A separate courier delivery method for Kyiv
• Street selection from a dropdown list
• Building number selection from a dropdown list
• A separate field for the apartment number
• Address loading from the Kyiv City State Administration registry
• Storage of the address directory in dedicated store database tables
• Manual synchronization from the administration panel
• Automatic full synchronization via cron
• Street search by individual words regardless of their order
• Search by part of a street name
• Basic matching of common Ukrainian and Russian spelling variants
• Configurable suggestion limits for streets and buildings
• Fixed courier delivery cost
• OpenCart geo zone support
• Configurable sort order
• Support for guest and registered customers
• Ukrainian, Russian, and English interface localization

Address Selection by the Customer

After selecting courier delivery, the customer completes the address step by step:

1. City — Kyiv, set automatically
2. Street — selected from the address directory suggestions
3. Building — selected from the list of buildings for the chosen street
4. Apartment — entered manually by the customer

The apartment number is entered separately because apartment data is not available in the public address registry. The street and building must be selected from the list, which helps prevent accidental errors and nonexistent addresses.

Street Search

The search is performed using individual words, so the order of words in the query does not matter. For example, the query Volodymyra Vysotskoho can find a name stored in the registry as Vysotskoho Volodymyra Boulevard.

Search by part of a name and basic matching of common Russian and Ukrainian variants are also supported. This helps customers find, for example, Beresteiskyi Avenue using an abbreviated or alternative spelling.

Kyiv City State Administration Address Directory

The extension receives city addresses from the Kyiv City State Administration address registry API. During synchronization, the complete available set of Kyiv streets and buildings is processed and then stored in separate OpenCart tables.

• The city, streets, and buildings are stored separately
• Repeated synchronization updates existing records
• New addresses are added automatically
• Outdated records are removed after successful synchronization
• Duplicate city, street, and building records are merged
• Simultaneous execution of multiple synchronization processes is blocked

Manual Synchronization

A Synchronize Addresses button is available in the extension settings. After synchronization is completed, the following information is displayed:

• synchronization status
• number of cities
• number of streets
• number of buildings
• date and time of the latest successful completion
• error message if the update was not completed

Automatic Updates via Cron

For regular directory updates, the extension generates a ready-to-use cron URL. Access to the URL is protected by a secret key between 16 and 128 characters long.

The URL can be added to the hosting or server task scheduler. Each run fully compares the local directory with the current API data.

Saving the Address in the Order

After validating the selected street and building, the extension creates the full delivery address and passes it to the standard OpenCart order creation process.

The street, building number, building section, and apartment are stored in the main delivery address field, shipping_address_1. The extension does not create the order separately and does not interfere with OpenCart’s standard order storage logic.

Multilingual Support

The administration panel and customer interface are localized in Ukrainian, Russian, and English.

If the API returns names in multiple languages, the extension can store the localized versions separately. If a translation for the current language is not available in the source, the primary registry name is used.

OCMOD Integration

Checkout integration is implemented through OCMOD. The extension does not require manual editing of OpenCart system files.

Compatibility

• OpenCart 3.x
• ocStore 3.x
• PHP 7.3–8.3
• Standard OpenCart 3.x checkout
• Ukrainian, Russian, and English localizations

System Requirements

• OpenCart or ocStore 3.x installed
• PHP 7.3–8.3
• MySQL or MariaDB
• The PHP cURL extension or permission to make HTTPS requests through allow_url_fopen
• Server access to the Kyiv City State Administration API over HTTPS
• The ability to configure cron for automatic directory updates

Important Limitations

• The extension is intended only for address delivery within Kyiv
• The completeness and accuracy of addresses depend on the data returned by the Kyiv City State Administration registry
• Street names are displayed in the format provided by the source
• Some addresses in the source may not include a postal code or building section
• The apartment number is entered manually by the customer
• The first synchronization processes the entire address directory and may take several minutes
• For automatic updates, the server must have stable access to the external API
• When the extension is uninstalled, the address directory tables created by it are also removed

Installation

1. Upload the courier_kyiv_v_1_0_oc3.ocmod.zip archive through Extensions → Installer
2. Go to Extensions → Modifications and refresh the modification cache
3. Go to Extensions → Extensions
4. Select Shipping as the extension type
5. Install the Courier Address Delivery in Kyiv extension
6. Open the extension settings
7. Select the geo zone and configure the delivery cost, sort order, and suggestion limit
8. Save a secure cron key containing at least 16 characters
9. Enable the extension and save the settings
10. Run a full address synchronization from the administration panel
11. Add the generated URL to the cron scheduler when necessary
12. Test street and building selection while placing a test order

License

One license covers one domain and all of its subdomains.