novaposhta-api-client

Python client for Nova Poshta company's API.

Installation

Client is based on python 3.6.

You can install package by using pip:

pip install git+https://github.com/semolex/novaposhta-api-client

Description

Client is based on models and signatures, provided in NovaPoshta API documentation.

Main idea of the client is to provide same methods as described there with minimal changes when it possible.

Methods and they parameters in most cases shares same names as in API docs, but in python-like style.

However, some models are omitted due to their singleton nature, for example, AddressGeneral model is part of the AddressModel, because it has only one method and semantically it is definitely part of the address-related items, etc. You can explore source code to find this parts.

Also, while there methods are designed to wrap same methods from API, there is may be some different and additions.

For example, some methods may be divided into smaller logical parts, because they uses a lot of parameters, also there is additional classes (WarehouseFilter and ExpressWaybill), used to divide some properties as separate class that can be passed to the method that will extract required parts.

There is a plans to add more logical chunks, so user can have different ways of manipulating complex parts.

Usage

To start using client, you need to have API key.

Methods returns requests.Response object so you have ability to add different checks and conversions, eg. check status codes, describe errors, warnings, etc.

Simple usage example:

from novaposhta import NovaPoshtaApi
# call api by using corresponding models
client = NovaPoshtaApi(api_key='your-api-key')
areas = client.address.get_areas() # models can be accessed as client properties
print(areas.json())

# call api by using `send` method from client.
reasons = client.send('AdditionalService', 'getReturnReasons', {})
print(reasons.json())

# you can pass parameters into method using two different ways.
# 1. Pass them directly.
cities_one = client.address.search_settlements(city_name='Здолбунів', limit=5)
# 2. Prepare required object as dictionary and unpack it.
query = {
    'city_name': 'Здолбунів',
    'limit': 5
}
cities_two = client.address.search_settlements(**query)

Plans to add before release version:

Add name mappings, so user can pass JSON object with same property names as in API docs. (eg. AddressCity can be used in dict object and then automatically converted into address_city)
Create test parts
Double check existing parameters, because API docs missing some small parts.
Add more classes that can represent data chunks so it will be possible to manipulate big objects easily.