Dictionaries
This API method allows you to retrieve a list of measurement units like pieces or meters or kilos, that you can use to specify your items by metric system. The response will include details of each measurement unit, such as the unit code, name, and any other relevant information. This data can be useful to generate a transportation document (shipment).
Authorization JWT-token with a lifetime of 1 hour in header
Max number of records to return on page.
15Example: 1Number of page to return
1measurements
Current page.
Total pages found.
Current objects` limit for a single page.
Total objects found.
Unauthorized
The specified resource was not found
Validation error
Connection time-out
GET /v.1.0/dictionary/measurements HTTP/1.1
Host: api-stage.novapost.com/
Authorization: YOUR_API_KEY
Accept: */*
{
"current_page": 1,
"last_page": 18,
"per_page": 1,
"total": 18,
"from": null,
"to": null,
"items": [
{
"code": "cm",
"name": "Centimeter",
"shortName": "cm",
"createdAt": "2022-09-29T09:16:04.000000Z",
"updatedAt": "2023-06-29T12:48:09.000000Z",
"deletedAt": null
}
]
}This API method enables you to obtain a list of own and partner`s cargo warehouses (divisions) and parcel lockers available within countries. By providing the country code as a parameter, you can retrieve a comprehensive list of cargo warehouses and related details. The response typically includes information such as warehouse name, number, address, ID, country and city details, warehouse type, work schedule, lunch breaks (for European divisions where applicable), and other relevant attributes. This data can be useful to generate a transportation document (shipment).
Authorization JWT-token with a lifetime of 1 hour in header
To receive a list of cargo warehouses and parcel lockers in a certain country please choose required country code from the list. Use code, according to the ISO 3166-1 Alpha-2 standard.
Max number of items to return.
15Example: 1Page number to return.
1List of settlement identifiers used to filter divisions or terminals by their location. Each ID corresponds to a unique settlement in the system.
Defines the operational category of a division to specify its type and function within the logistics network. Use one or multiple categories from the list.
Filters divisions by their operational status. Indicates whether the branch is active, temporarily closed, or in preparation for opening.
By default, only divisions with the Working status are returned.
Indicates whether sending parcels from this division is available. If true – sending from this division is not possible.
Indicates whether parcel delivery to this division is available. If true – receiving parcels at this division is not possible.
Geographical latitude of the division, used for positioning on maps and calculating distances. Example value: 49.8005164984.
Geographical longitude of the division, used for positioning on maps and calculating distances. Example value: 22.9404162762.
To receive warehouse description in a certain language please put required language code (ISO 639-1 standard) in a header parameter with a name - accept-language. If there is no translation for the selected language, then English will be displayed
Divisions
Current page.
Total pages found.
Current objects` limit for a single page.
Total objects found.
Unauthorized
The specified resource was not found
Validation error
Connection time-out
GET /v.1.0/divisions HTTP/1.1
Host: api-stage.novapost.com/
Authorization: YOUR_API_KEY
Accept: */*
{
"current_page": 1,
"last_page": 24942,
"per_page": 1,
"total": 24942,
"from": null,
"to": null,
"items": [
{
"id": 1,
"name": "WROCŁAW 1",
"shortName": "WROCŁAW 1",
"externalId": "cf909742-1bee-4c97-8d0e-16de519c3220",
"source": "NPAX",
"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 dolnośląskie, Wrocław County, Wrocław, Trzebnicka, 50/1A",
"number": "50/1",
"status": "Working",
"customerServiceAvailable": true,
"divisionCategory": "PostBranch",
"publicPhones": [],
"internalPhones": [],
"responsiblePerson": "Dzhemesiuk Yaroslav",
"partner": null,
"ownerDivision": null,
"latitude": 51.1271131131,
"longitude": 17.0360840848,
"distance": null,
"maxWeightPlaceSender": 200000,
"maxLengthPlaceSender": 3000,
"maxWidthPlaceSender": 1700,
"maxHeightPlaceSender": 1700,
"maxWeightPlaceRecipient": 200000,
"maxLengthPlaceRecipient": 3000,
"maxWidthPlaceRecipient": 1700,
"maxHeightPlaceRecipient": 1700,
"prohibitedSending": false,
"prohibitedIssuance": false,
"maxCostPlace": 999999,
"maxDeclaredCostPlace": 999999,
"workSchedule": [
{
"day": "sunday",
"from": "09:00",
"to": "18:00",
"breakFrom": null,
"breakTo": null
},
{
"day": "monday",
"from": "08:00",
"to": "20:00",
"breakFrom": null,
"breakTo": null
},
{
"day": "tuesday",
"from": "08:00",
"to": "20:00",
"breakFrom": null,
"breakTo": null
},
{
"day": "wednesday",
"from": "08:00",
"to": "20:00",
"breakFrom": null,
"breakTo": null
},
{
"day": "thursday",
"from": "08:00",
"to": "20:00",
"breakFrom": null,
"breakTo": null
},
{
"day": "friday",
"from": "08:00",
"to": "20:00",
"breakFrom": null,
"breakTo": null
},
{
"day": "saturday",
"from": "09:00",
"to": "18:00",
"breakFrom": null,
"breakTo": null
}
],
"settings": [],
"logisticsCode": "Code.1",
"attributes": {
"printFormDeliveryRegion": "Balty"
},
"createdAt": "2022-09-29T12:40:39.000000Z",
"updatedAt": "2023-10-16T10:06:35.042931Z",
"deletedAt": null,
"fullAddress": {
"country": "Poland",
"settlement": "Wrocław",
"street": "Trzebnicka",
"building": "50/1A",
"note": "",
"zipcode": "50-231"
}
}
]
}This API method returns a manifest with links to offline dictionary files containing data on own and partner cargo divisions and parcel lockers.
The response includes URLs to the latest localized dictionary files prepared for offline use. Each file typically contains information such as division name, number, address, ID, country and city, division type, working hours, lunch breaks (for European divisions where applicable), and other relevant attributes. This data can be used to generate a shipment.
The dictionary files contain data for all divisions and are distributed as localized compressed JSON archives in the .json.gz format.
🔹The dictionary is updated once per day and is intended for offline use and periodic synchronization. To obtain the latest version of the dictionary, use the URL provided in the current API response. It is not recommended to use URLs obtained from previous responses.
Returns the metric system in kilograms (kg) and centimeters (cm), or grams (g) and millimeters (mm).
The default value is kg_cm. If any other value is provided, a 422 validation error will be returned.
kg_cmPossible values: To receive the dictionary content in a specific language, provide the required language code (ISO 639-1) in the Accept-Language header.
If a translation is not available for the selected language, English will be used. The default value is en.
enPossible values: Divisions offline dictionary manifest
Validation error
Time-out
GET /v.1.0/dictionary/divisions HTTP/1.1
Host: api-stage.novapost.com/
Accept: */*
{
"base_version": {
"unix_time": 1786294841,
"url": "https://api-cdn.novapost.com/dictionary/divisions/api/en/base.json.gz"
},
"deltas": [
{
"unix_time_from": 1786035632,
"unix_time_till": 1786122036,
"url": "https://api-cdn.novapost.com/dictionary/divisions/api/en/delta_1786122036.json.gz"
},
{
"unix_time_from": 1786122036,
"unix_time_till": 1786208439,
"url": "https://api-cdn.novapost.com/dictionary/divisions/api/en/delta_1786208439.json.gz"
},
{
"unix_time_from": 1786208439,
"unix_time_till": 1786294841,
"url": "https://api-cdn.novapost.com/dictionary/divisions/api/en/delta_1786294841.json.gz"
}
]
}This API method allows you to retrieve a list of currencies that are available for creating transportation documents. By making a request with this method, you can obtain a list of currencies supported by the system. The response will include details of each currency, such as the currency code, name, and any other relevant information. This data can be useful to generate a transportation document (shipment).
Authorization JWT-token with a lifetime of 1 hour in header
Max number of items to return on page.
15Example: 1Number of page to return.
1Currencies codes.
UAHcurrencies
Current page.
Total pages found.
Current objects` limit for a single page.
Total objects found.
Unauthorized
The specified resource was not found
Validation error
Connection time-out
GET /v.1.0/dictionary/currencies HTTP/1.1
Host: api-stage.novapost.com/
Authorization: YOUR_API_KEY
Accept: */*
{
"current_page": 1,
"last_page": 1,
"per_page": 1,
"total": 1,
"from": null,
"to": null,
"items": [
{
"code": "USD",
"numCode": "840",
"name": "US Dollar",
"shortName": "US Dollar",
"symbol": "$",
"createdAt": "2022-09-27T11:55:52.000000Z",
"updatedAt": "2022-09-27T11:55:52.000000Z",
"deletedAt": null
}
]
}This API method allows you to retrieve a list of cargo classifiers (UKT ZED). Cargo classifiers are predefined categories or classifications used to categorize different types of cargo. By making a request to this method, you can obtain a list of cargo classifiers supported by the system. The response will include details of each classifier, such as the classifier ID, name, description, category, examples and any other relevant information. This data can be useful to generate a transportation document (shipment).
How it works:
The method returns classifiers for the recipient country specified in the
country-codeparameter.The format of UKT ZED codes depends on the selected country, example:
For destination countries Canada (CA) and Moldova (MD), UKT ZED codes are strictly validated to be exactly 10 digits.
Any non-numeric characters included in the
HsCodewill be automatically removed before validation.
The
keywordparameter enables searching for a specific product classifier.If
fuzzy=true, the search will include similar results based on approximate matching.
Limitations:
Some countries may not support UKT ZED retrieval via API.
Results depend on the latest classifier database updates.
Authorization JWT-token with a lifetime of 1 hour in header
The ISO 3166-1 Alpha-2 code of the country for which the UKT ZED classifier is needed.
This parameter refers to the recipient country, not the sender.
The format of UKT ZED codes varies by country, example:
UA– Returns 8-digit codes.CAorMD– Returns 10-digit codes.
Example: If you need UKT ZED codes for Canada, use country-code=CA.
CASearch mechanism enables to include results that closely resemble the query terms or have some degree of similarity, expanding the search scope to include variations or similar entries.
truePossible values: Search keyword for the classifier.
bookLanguage code according to ISO 639-1 standard.
ukNumber of matching classifiers to return.
15List of cargo classifiers (UKT ZED)
Unauthorized
The specified resource was not found
Validation error
Connection time-out
GET /v.1.0/dictionary/classifier HTTP/1.1
Host: api-stage.novapost.com/
Authorization: YOUR_API_KEY
Accept: */*
{
"status": true,
"source": "tda",
"error": "",
"items": [
{
"id": "b1f6e933-a5fd-3c76-8663-49ad7b454bdd",
"hsCode": "85171400",
"category": {
"en": "Electronics",
"currentLocal": "Електроніка"
},
"subCategory": {
"en": "Laptops, Computers And Peripherals",
"currentLocal": "Ноутбуки, комп'ютери та периферійні пристрої"
},
"keywords": {
"en": "Avonic Video Conference Camera, System for video conferences, IP conference phone, Logitech ConferenceCam, Prestigio Solutions, UHD video conference camera, USB speakerphone, Device for conference communication, Wireless speakerphone, Video conference camera, VKZ camera, Video conference kit, Conference Lenovo hub, Speakerphone, Speaker system, Audio conference system, Conference phone, Video conference system, Notification system, System console",
"currentLocal": "Avonic Video Conference Camera, Cистема для відеоконференцій, IP конференц телефон, Logitech ConferenceCam, Prestigio Solutions, UHD відео конференц камера, USB спікерфон, Апарат для конференц зв'язку, Бездротовий спікерфон, Камера відеоконференції, Камера ВКЗ, Комплект для відеоконференцзв'язку, Конференц хаб Lenovo, Спікерфон, Акустична система, Аудіо конференц система, Конференц-телефон, Система відеоконференції, Система оповіщення, Системна консоль"
},
"product": {
"en": "Conference equipment",
"currentLocal": "Конференц-обладнання"
},
"description": {
"en": "Electrical machinery and equipment and parts thereof; sound recorders and reproducers, television image and sound recorders and reproducers, and parts and accessories of such articles | Telephone sets, including smartphones and other telephones for cellular networks or for other wireless networks; other apparatus for the transmission or reception of voice, images or other data, including apparatus for communication in a wired or wireless network (such as a local or wide area network), other than transmission or reception apparatus of heading 8443, 8525, 8527 or 8528; parts thereof: | Telephone sets, including smartphones and other telephones for cellular networks or for other wireless networks : | Other telephones for cellular networks or for other wireless networks | Other",
"currentLocal": "Електричні машини та обладнання та їх частини; апарати для запису та відтворення звуку, апарати для запису та відтворення телевізійного зображення та звуку, а також частини та приладдя до таких виробів | Телефонні апарати, включаючи смартфони та інші телефони для стільникових мереж або інших бездротових мереж; інша апаратура для передачі або прийому голосу, зображень або інших даних, включаючи апаратуру для зв'язку в дротовій або бездротовій мережі (такій як локальна або глобальна мережа), крім апаратури для передачі або прийому товарних позицій 8443, 8525, 8527 або 8528; їх частини: | Телефонні апарати, включаючи смартфони та інші телефони для стільникових мереж або інших бездротових мереж: | Інші телефони для стільникових мереж або для інших бездротових мереж | Інший"
},
"exportFromUA": true,
"importToUA": true
}
]
}This method returns recipient country settings used to determine whether customs duties can be paid by the sender, as well as the minimum and maximum declared parcel value thresholds within which this option is available.
If the customsFeesActive value is false, the sender cannot act as the customs-duty payer for the selected country.
The minDeclaredCost and maxDeclaredCost fields define the declared parcel value range (in the recipient country's currency) within which the option for customs-duty payment by the sender is available.
If the declared parcel value is lower than minDeclaredCost, customs duties are not applied to the parcel.
If the declared parcel value exceeds maxDeclaredCost, the sender cannot act as the customs-duty payer. In this case, the payerFeesCustoms parameter must be set to Recipient.
Authorization JWT-token with a lifetime of 1 hour in header
Alpha-code of the destination country according to the ISO 3166-1 Alpha-2
PLSuccessful response with customs-fee configuration
Indication of the possibility of paying customs duties by the sender.
Possible values:
true— payment is possiblefalse— payment is not possible
trueMinimum declared parcel value in the recipient country's currency.
10Maximum declared parcel value in the recipient country's currency.
500Unauthorized
Unprocessable entity – invalid country code
Connection time-out
GET /v.1.0/dictionary/customs-fees/{code} HTTP/1.1
Host: api-stage.novapost.com/
Authorization: YOUR_API_KEY
Accept: */*
{
"customsFeesActive": true,
"maxDeclaredCost": 500,
"minDeclaredCost": 10
}This API method returns a manifest with links to offline dictionary files listing Ukrainian settlements where shipment issuance (pickup) is prohibited. The dictionary covers all settlement types and is intended for address validation, delivery availability checks, and logistics restrictions.
The response contains URLs to the latest localized dictionary files prepared for offline usage. Each file includes settlement data such as administrative hierarchy, coordinates, postal codes, alternative names, and prohibition flags.
The dictionary files are distributed as localized compressed JSON archives.
🔹Key features:
Returns a JSON manifest with URLs to dictionary files.
Files are provided in
.json.gzformat.Localization supported (
locale="uk",locale="en").Includes only settlements with
prohibitedIssuance = true.Designed for offline usage and periodic synchronization.
Authorization JWT-token with a lifetime of 1 hour in header
Settlement prohibited issuance dictionary manifest
Unix timestamp indicating the dictionary generation time.
1766120417List of URLs to localized offline dictionary files.
https://api-cdn.novapost.com/dictionary/settlements/prohibited-issuance/en/settlements.json.gzUnauthorized
Action not available
GET /v.1.0/dictionary/settlements/prohibited-issuance HTTP/1.1
Host: api-stage.novapost.com/
Authorization: YOUR_API_KEY
Accept: */*
{
"unix_time": 1766120417,
"urls": [
"https://api-cdn.novapost.com/dictionary/settlements/prohibited-issuance/en/settlements.json.gz",
"https://api-cdn.novapost.com/dictionary/settlements/prohibited-issuance/uk/settlements.json.gz"
]
}This API method returns a manifest with links to offline dictionary files containing settlements. The dictionaries are generated based on the settlements dataset and provided separately per country.
The response contains URLs to the latest localized dictionary files prepared for offline usage. Each file includes settlement data such as administrative hierarchy, coordinates, postal codes, alternative names, and other relevant attributes.
Each request returns dictionary files for a specific country.
The dictionary files are distributed as localized compressed JSON archives.
🔹Key features:
Returns a JSON manifest with URLs to dictionary files.
Files are provided in
.json.gzformat.Localization supported via
Accept-languageheader (default:en).Separate files per country (
UA,MD).Based on settlements dictionary data.
Updated once per day.
Designed for offline usage and periodic synchronization.
Authorization JWT-token with a lifetime of 1 hour in header
Country code for which the settlements dictionary should be returned (ISO 3166-1 Alpha-2).
UAPossible values: To receive dictionary content in a certain language please put required language code (ISO 639-1 standard) in a header parameter with a name - accept-language. If there is no translation for the selected language, then English will be displayed
Settlements offline dictionary manifest
Unix timestamp indicating the dictionary generation time.
1776225628List of public URLs to localized offline dictionary files.
https://api-cdn.novapost.com/dictionary/settlements/api/UA/uk/base.json.gzUnauthorized
Action not available
Connection time-out
GET /v.1.0/dictionary/settlements/versions?countryCode=UA HTTP/1.1
Host: api-stage.novapost.com/
Authorization: YOUR_API_KEY
Accept: */*
{
"unix_time": 1776225628,
"base_version": {
"unix_time": 1776225628
},
"urls": [
"https://api-cdn.novapost.com/dictionary/settlements/api/UA/uk/base.json.gz"
]
}This API method enables you to get a list of settlements available in different countries. By providing the country code as a parameter, you can retrieve a complete list of settlements and their associated information. The method supports searching by street name. The response usually contains information such as the settlement name, identifier, country data, and other relevant attributes. This data can be useful for creating a transport document (shipment).
Authorization JWT-token with a lifetime of 1 hour in header
To receive a list of settlements in a certain country please choose required country code from the list. Use code, according to the ISO 3166-1 Alpha-2 standard.
Max number of items to return.
15Example: 1Page number to return.
1Search by any text.
settlements
Current page.
Total pages found.
Current objects` limit for a single page.
Total objects found.
Unauthorized
The specified resource was not found
Validation error
Connection time-out
GET /v.1.0/settlements HTTP/1.1
Host: api-stage.novapost.com/
Authorization: YOUR_API_KEY
Accept: */*
{
"current_page": 1,
"last_page": 80,
"per_page": 15,
"total": 1186,
"from": null,
"to": null,
"items": [
{
"id": 118064,
"name": "місто Київ",
"country": {
"code": "UA",
"name": "Україна"
},
"region": {
"id": 406,
"name": "Київська область",
"parent": null
},
"latitude": 50.450418,
"longitude": 30.523541,
"postCode1": "01001",
"postCode2": "04215",
"alternativeNames": [
"kyiv",
"місто київ",
"misto kiyiv",
"город киев",
"gorod kiev",
"city kyiv"
],
"externalId": "e718a680-4b33-11e4-ab6d-005056801329",
"boost": 504,
"prohibitedIssuance": false,
"prohibitedSending": false,
"createdAt": "2022-10-01T15:50:20.000000Z",
"updatedAt": "2026-04-03T07:17:49.715827Z",
"deletedAt": null
}
]
}This API method enables you to get a list of streets available in different settlements. By providing the country code as a parameter or settlementId as parameter, you can retrieve a complete list of streets and their associated information. The method also supports searching by street name. The response usually contains information such as the street name, settlement name, identifier and other relevant attributes. This data can be useful for creating a transport document (shipment).
Authorization JWT-token with a lifetime of 1 hour in header
List of country codes (ISO 3166-1 Alpha-2) to filter streets.
Street name filter.
Max number of items to return.
15Example: 15Page number to return.
1streets
Current page.
Total pages found.
Current objects` limit for a single page.
Total objects found.
Unauthorized
The specified resource was not found
Validation error
Connection time-out
GET /v.1.0/streets HTTP/1.1
Host: api-stage.novapost.com/
Authorization: YOUR_API_KEY
Accept: */*
{
"current_page": 1,
"last_page": 1,
"per_page": 50,
"total": 16,
"from": null,
"to": null,
"items": [
{
"id": 4582148,
"name": "вул. Хрещатик",
"settlement": {
"id": 118064,
"name": "місто Київ"
},
"countryCode": "UA",
"latitude": 0,
"longitude": 0,
"alternativeNames": [
"вул. хрещатик",
"vul. khreshchatik",
"крещатик",
"kreshchatik",
"khreshchatyk"
],
"externalId": "ad090b1f-6845-11e6-8304-00505688561d",
"createdAt": "2024-02-03T11:40:00.000000Z",
"updatedAt": "2025-04-04T00:47:48.223218Z",
"deletedAt": null
}
]
}Last updated