Eng
Directory of branches
integration

The Branch Directory is an important element of integration with the Nova Post API. It provides up-to-date information on all Nova Post branches and partners, including addresses, working hours, coordinates, and other parameters.

The NovaPost API branch directory method allows flexible access to up-to-date information about branches in real-time or downloading the full directory for later use. The choice of approach depends on your data volume needs and update frequency: 

Retrieve Branch Data in Real-Time

To get branch information in real-time, you can use an API request.

Example request:

GET https://api.novapost.com/v.1.0/divisions?countryCodes[]=PL&limit=100&name=*WROCŁAW*

Possible Additional Filters:

  • 1
    divisionCategories[]: Branch categories. Possible values: PostBranch, CargoBranch, Postomat, PUDO.
  • 2
    countryCodes[]: Two-letter country code (e.g., PL, UA, HU).
  • 3
    name: City name in Ukrainian, English, or the language of the country where the city is located.

  • Example response:

    {
        "id": 1,
        "name": "WROCŁAW 1",
        "shortName": "WROCŁAW 1",
        "number": "50/1",
        "countryCode": "PL",
        "settlement": {
            "id": 26061,
            "name": "Wroclaw",
            "region": {
                "id": 344,
                "name": "Wrocław County",
                "parent": {
                    "id": 2,
                    "name": "Lower Silesian voivodeship"
                }
            }
        },
        "address": "50-231, Polska, Województwo dolноśląське, Wrocław County, Wrocław, Trzebnickа, 50/1A",
        "status": "Working",
        "divisionCategory": "PostBranch",
        "latitude": 51.1271131131,
        "longitude": 17.0360840848,
        "workSchedule": [
            {
                "day": "monday",
                "from": "08:00",
                "to": "20:00"
            },
            {
                "day": "tuesday",
                "from": "08:00",
                "to": "20:00"
            },
            {
                "day": "wednesday",
                "from": "08:00",
                "to": "20:00"
            },
            {
                "day": "thursday",
                "from": "08:00",
                "to": "20:00"
            },
            {
                "day": "friday",
                "from": "08:00",
                "to": "20:00"
            },
            {
                "day": "saturday",
                "from": "09:00",
                "to": "18:00"
            },
            {
                "day": "sunday",
                "from": "09:00",
                "to": "18:00"
            }
        ]
    }

Download the Entire Branch Directory

If you need complete information about all branches rather than just a subset of data, it is recommended to download the branch directory as an archive.

Example request:

GET https://api.novapost.com/divisions/versions

This request can be executed without an authorization token. If necessary, the response language of the directory can be changed by passing a language parameter in the request header, for example, Accept-Language:uk.

  • Example response:

    {
        "base_version": {
            "unix_time": 1710198943,
            "url": "https://api-cdn.novapost.pl/dictionary/divisions/mobile/full/en/base.json.gz"
        },
        "deltas": [
            {
                "unix_time_from": 1709928943,
                "unix_time_till": 1709961345,
                "url": "https://api-cdn.novapost.pl/dictionary/divisions/mobile/full/en/delta_1709961345.json.gz"
            },
            {
                "unix_time_from": 1709961345,
                "unix_time_till": 1710015350,
                "url": "https://api-cdn.novapost.pl/dictionary/divisions/mobile/full/en/delta_1710015350.json.gz"
            }
        ]
    }

  • 1
    base_version: A link to the full branch directory at the time of the last update.
  • 2
    deltas: Links to files that contain updates to the branch directory recorded after the creation of the base version.

Using the archive and deltas

Downloading the base version archive of the directory provides a complete list of branches. After that, only the changes can be updated using delta files, significantly reducing the volume of data to process.