Pickup Points Database

The plugin stores all Slovenská Pošta pickup point data in a dedicated local database. This design means:

Note: The Pošta Widget does not use this local pickup points database. It loads pickup points directly from Slovenská Pošta’s servers. The local database is used only by the built-in map mode.

• No live API calls during checkout — all pickup point lookups (search, nearby, details) are performed against your local WordPress database. Checkout performance is not affected by Slovenská Pošta’s server availability.
• Fast search — indexed database queries return results in milliseconds, even with thousands of pickup points.
• Offline resilience — if Slovenská Pošta’s servers are down, your checkout continues to work with the last imported dataset.

---

Data Source

Pickup point data is imported from an XML feed provided by Slovenská Pošta:

Default URL:

https://www.posta.sk/public/forms/zoznam_post.xml

This URL can be overridden in wp-config.php using the WCSP_PICKUP_POINTS_XML_URL constant.

The XML contains:

• Post office and BalikoBOX location identifiers
• Names and full addresses
• GPS coordinates (latitude and longitude)
• Maximum accepted weight per pickup point
• Opening hours (as structured XML)
• Notes and special instructions

---

Services

The plugin recognizes two service codes:

A single physical location can offer both services (e.g., a post office that also hosts a BalikoBOX locker). The many-to-many relationship between pickup points and services is stored in a junction table.

---

Data Freshness

Slovenská Pošta periodically updates its pickup point network — opening new offices, closing others, and changing opening hours. To keep your local data current, the plugin supports both manual updates and automatic scheduled updates.

Note: Keeping the local database up to date is relevant only for the built-in map mode. The Pošta Widget uses Slovenská Pošta’s live data instead.

The last update timestamp is displayed in the Pickup Points DB settings tab.

---

Related Pages

• Updating Pickup Points — How to trigger manual and automatic updates.
• Database Tables — Complete schema for the three custom tables.

Updating Pickup Points

Manual Update

Note: These database updates affect only the built-in map mode. The Pošta Widget does not use the local pickup points database.

To immediately refresh the pickup point data:

1. Navigate to WP-Admin > Slovenská Pošta > Pickup Points DB.
2. Click Update Now.
3. An AJAX request is sent to the server, which fetches and processes the XML feed.
4. The page displays a success message with the updated counts, or an error message if the update fails.

The manual update process is also available programmatically. The admin AJAX action wcsp_update_pickup_points_db can be triggered with a valid admin nonce.

---

Automatic Updates

Note: Automatic updates keep the local pickup points database current for the built-in map mode only. They do not affect the Pošta Widget.

Enable automatic updates to keep pickup point data current without manual work:

1. Navigate to WP-Admin > Slovenská Pošta > Pickup Points DB.
2. Check Enable Automatic Updates.
3. Select an Update Frequency from the dropdown.
4. Save settings.

The plugin registers a WP-Cron event that fires on the selected schedule.

Available frequencies:

Recommendation: Weekly is sufficient for most stores.

---

The Update Process

When an update runs (manually or automatically), the following steps occur:

1. Fetch — The plugin downloads the XML file from the configured URL (timeout: 120 seconds).
2. Validate — The downloaded XML is parsed and <POSTA> entries are counted. If fewer than 100 valid entries are found, the update is aborted to prevent replacing the database with a partial or corrupted feed.
3. Save locally — The validated XML is written to feed/zoznam_post.xml inside the plugin directory, replacing the previously bundled file.
4. Import — The existing pickup point data is truncated and replaced with the new dataset. The import is done in batches of 250 records for memory efficiency.
5. Timestamp — The wcsp_last_sync option is updated with the current time.

---

Update Safety Guard

The 100-entry threshold is a safeguard against:

• Incomplete XML feeds (network interruptions mid-download)
• Empty or malformed feed responses
• Slovenská Pošta temporarily returning an error page instead of XML

If the safety check fails, the existing database is preserved unchanged and an error is logged (visible in the admin update response).

---

WP-Cron Dependency

Automatic updates rely on WordPress’s built-in WP-Cron system. WP-Cron is triggered by site traffic — it runs when a page is loaded, not at a fixed clock time.

Implications:

• On high-traffic sites, cron events fire close to their scheduled time.
• On low-traffic sites, events may be delayed until the next page load after the scheduled time.

For guaranteed scheduling on low-traffic sites, disable WP-Cron’s standard behavior and use a real server cron job:

1. Add to wp-config.php:

   define( 'DISABLE_WP_CRON', true );
   

2. Add a server cron job (e.g., every 5 minutes):

   */5 * * * * curl -s https://yoursite.com/wp-cron.php > /dev/null 2>&1
   

---

Changing the Feed URL

By default, data is fetched from https://www.posta.sk/public/forms/zoznam_post.xml. To use a different URL, define this constant in wp-config.php:

define( 'WCSP_PICKUP_POINTS_XML_URL', 'https://your-url.com/custom-feed.xml' );

Database Tables

The plugin creates three custom database tables on activation. Table names use the WordPress table prefix (e.g., wp_ by default).

---

Table: {prefix}wcsp_pickup_points

The main table storing all pickup point records.

Indexes:

• ref_id — unique index for fast lookups by Slovenská Pošta ID
• address_zip — index for postal code searches
• address_city — index for city searches
• lat, lng — individual indexes supporting coordinate-based queries

---

Table: {prefix}wcsp_services

A lookup table for service codes. Typically contains two rows after import.

Standard rows:

---

Table: {prefix}wcsp_pickup_point_services

A junction table linking pickup points to the services they offer. A single pickup point can offer both BNP and BBOX.

Constraint: The combination of pickup_point_id + service_id is unique — a pickup point cannot be linked to the same service twice.

---

Table Creation and Updates

Tables are created using WordPress’s dbDelta() function on plugin activation. This function safely applies schema changes without data loss, making it suitable for plugin updates that alter the table structure.

If a table already exists with the correct schema, dbDelta() makes no changes. If columns are missing or types differ, it applies the necessary alterations.

---

Querying the Tables

The plugin provides a WCSP_Pickup_Points class with methods for all common queries. Direct SQL queries are generally not necessary. Available methods include:

• get_all_map_markers( $service_code, $exclude_bbox ) — Returns all lat/lng coordinates for map marker initialization.
• search( $term, $service_code, $exclude_bbox ) — Text search by name, city, or postal code.
• get_closeby( $lat, $lng, $limit, $service_code, $exclude_bbox ) — Haversine-based proximity search.
• get_details( $id ) — Full details for a single pickup point including formatted opening hours.
• can_accept_weight( $id, $weight_kg ) — Boolean weight limit check.

See AJAX Endpoints for how these are exposed to the frontend.