{"id":37067315,"url":"https://github.com/semolex/novaposhta-python-client","last_synced_at":"2026-01-14T07:54:04.129Z","repository":{"id":44561116,"uuid":"42809222","full_name":"semolex/novaposhta-python-client","owner":"semolex","description":"Python client for Nova Poshta API.","archived":false,"fork":false,"pushed_at":"2025-04-25T14:27:10.000Z","size":171,"stargazers_count":31,"open_issues_count":0,"forks_count":18,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-09-28T19:23:15.592Z","etag":null,"topics":["api","api-client","api-wrapper","nova-poshta","nova-poshta-api-client","novaposhta","novaposhta-api","novaposhta-client","python","python-client"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/semolex.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.md","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2015-09-20T10:39:13.000Z","updated_at":"2025-09-25T08:12:13.000Z","dependencies_parsed_at":"2024-12-04T14:31:19.968Z","dependency_job_id":null,"html_url":"https://github.com/semolex/novaposhta-python-client","commit_stats":null,"previous_names":["semolex/novaposhta-python-client","semolex/novaposhta-api-client"],"tags_count":5,"template":false,"template_full_name":null,"purl":"pkg:github/semolex/novaposhta-python-client","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/semolex%2Fnovaposhta-python-client","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/semolex%2Fnovaposhta-python-client/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/semolex%2Fnovaposhta-python-client/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/semolex%2Fnovaposhta-python-client/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/semolex","download_url":"https://codeload.github.com/semolex/novaposhta-python-client/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/semolex%2Fnovaposhta-python-client/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28413519,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-14T05:26:33.345Z","status":"ssl_error","status_checked_at":"2026-01-14T05:21:57.251Z","response_time":107,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api","api-client","api-wrapper","nova-poshta","nova-poshta-api-client","novaposhta","novaposhta-api","novaposhta-client","python","python-client"],"created_at":"2026-01-14T07:54:03.408Z","updated_at":"2026-01-14T07:54:04.123Z","avatar_url":"https://github.com/semolex.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# novaposhta-python-client\n\nA Python client for interfacing with the Nova Poshta API. Designed to provide easy access to all API functionalities\nwith emphasis on consistency and usability.\n\n[![Tests](https://github.com/semolex/novaposhta-python-client/actions/workflows/tests.yml/badge.svg)](https://github.com/semolex/novaposhta-python-client/actions/workflows/tests.yml)\n[![License](https://img.shields.io/github/license/semolex/novaposhta-python-client)](https://github.com/semolex/novaposhta-python-client/blob/master/LICENSE.md)\n[![PyPI](https://img.shields.io/pypi/v/novaposhta-python-client)](https://pypi.org/project/novaposhta-python-client/)\n[![Downloads](https://pepy.tech/badge/novaposhta-python-client)](https://pepy.tech/project/novaposhta-python-client)\n[![Downloads](https://pepy.tech/badge/novaposhta-python-client/month)](https://pepy.tech/project/novaposhta-python-client)\n[![Python Versions](https://img.shields.io/pypi/pyversions/novaposhta-python-client.svg)](https://pypi.org/project/novaposhta-python-client/)\n[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)\n[![Imports: isort](https://img.shields.io/badge/%20imports-isort-%231674b1)](https://pycqa.github.io/isort/)\n\n## Description\n\nThis client is compatible with `python = \"^3.9\"` and aims to mirror the Nova Poshta API's endpoints, offering a 1:1\nmapping where possible. However, users should be aware of the inconsistencies and occasional ambiguities present in the\nAPI. This can affect the signatures of some methods, and special attention is needed when working with endpoints like\nthe `save` method from some models which can create different items based on the provided input.\n\nEfforts to enhance the consistency and robustness of the client are ongoing, and future releases will focus on thorough\ntesting and refinement of all possible parameter combinations.\n\n## Installation\n\n```bash\npip install novaposhta-python-client\n```\n\n## Usage\n\nHere's a basic example of how to use the client:\n\n```python\nfrom novaposhta.client import NovaPoshtaApi\n\n# Instantiate the client\nclient = NovaPoshtaApi('my-api-token', timeout=30)\n\n# Example usage of different models\nsettlements = client.address.search_settlements(city_name='Київ', limit=5)\nmy_pack_list = client.common.get_pack_list(length=1, width=5)\nreturn_reason = client.additional_service.get_return_reasons()\n\n# Print results\nprint(settlements, my_pack_list, return_reason)\nclient.close_sync()\n```\nPlease, close the client whenever you are done with it to avoid resource leaks.\n\nYou can also use async client:\n\n```python\nimport asyncio\nfrom novaposhta.client import NovaPoshtaApi\n\nasync def use_api_async():\n    async_client = NovaPoshtaApi('your_api_key', timeout=30, async_mode=True, raise_for_errors=True)\n    address = async_client.address\n    settlements = await address.search_settlements(city_name='Київ', limit=5)\n    print(settlements)\n    await async_client.close_async()\nasyncio.run(use_api_async())\n```\n\nYou can use context manager to automatically close the client:\n\n```python\nfrom novaposhta.client import NovaPoshtaApi\ndef use_api_sync():\n    with NovaPoshtaApi(api_key='your_api_key', async_mode=False) as api:\n        # Do something with the API\n        pass\n\nasync def use_api_async():\n    async with NovaPoshtaApi(api_key='your_api_key', async_mode=True) as api:\n        # Do something with the API\n        pass\n```\n\n## Error handling\n\n```python\nimport httpx\nfrom novaposhta.client import NovaPoshtaApi, InvalidAPIKeyError, APIRequestError\n\n# Instantiate the client\nclient = NovaPoshtaApi('your_api_key', timeout=30, raise_for_errors=True)\n\ntry:\n    client.common.get_cargo_types()\nexcept httpx.HTTPError as error:\n    print(f\"HTTP error: {error}\")\nexcept InvalidAPIKeyError as error:\n    print(f\"API key expired or otherwise invalid: {error}\")\nexcept APIRequestError as error:\n    print(f\"Something else is wrong with API request: {error}\")\n```\n\n## Extending the Client\n\n### Custom HTTP Client\n\nWhile `httpx` is the default HTTP library, you can easily substitute it with requests or another library, provided it\nfollows the same interface:\n\n```python\nfrom novaposhta.client import NovaPoshtaApi\nimport my_http_client\n\nclient = NovaPoshtaApi('your_api_key', http_client=my_http_client.Client)\n```\n\n### Adding New Methods\n\nIf a method isn’t implemented, or you prefer a custom implementation, extend the model as shown below:\n\n```python\nfrom novaposhta.models.base import BaseModel, api_method\n\n\nclass MyCustomModel(BaseModel):\n    @api_method('MissingMethod')\n    def missing_method(self, some_param: str):\n        return self._call_with_props(SomeParam=some_param)\n```\n\nThe client caches all model instances. To reset and create a new model instance, use the new method:\n\n```python\nfrom novaposhta.client import NovaPoshtaApi\nfrom novaposhta.models.address import Address\n\nclient = NovaPoshtaApi('my-api-token')\naddress = client.new(Address)\n```\n\nTo get your custom model instance, use the get method:\n\n```python\nmy_custom_model = client.get(MyCustomModel.name)\n```\n\n## Experimental: Chain Operations\n\nThe chain functionality allows you to sequence multiple API operations, where each operation's output can be transformed and passed to the next operation. This is particularly useful for scenarios that require multiple dependent API calls, like searching for addresses or creating shipments.\nEach result of `prepare_next` is passed to the next operation as updated `kwargs`.\n\u003e ⚠️ **Note**: This feature is experimental and currently optimized for async usage.\n\n### Basic Usage\n\n```python\nfrom novaposhta.client import NovaPoshtaApi\nfrom novaposhta.chains import Chain \n\n# Initialize client in async mode\nclient = NovaPoshtaApi(\"API_KEY\", async_mode=True)\n\n# Create a chain of operations\nchain = (\n    Chain(\n        client.address.get_areas,\n        prepare_next=lambda x: {'ref': x['data'][0]['AreasCenter']}\n    ) |\n    Chain(\n        client.address.get_cities,\n        prepare_next=lambda x: {'city_ref': x['data'][0]['Ref']}\n    ) |\n    Chain(\n        client.address.get_street,\n        kwargs={'find_by_string': 'Street Name'}\n    )\n)\n\n# Execute chain\nresults = await chain.execute_async()\n```\n\n### Features\n\n- Chain multiple API operations using the `|` operator\n- Transform operation results for next operation using `prepare_next`\n- Automatic error handling and chain interruption on failure\n- Preserve both original API responses and transformed data\n- Initial parameters via `kwargs`\n\n### Common Patterns\n\n```python\n# Address search chain\nfrom novaposhta.client import NovaPoshtaApi\n\nclient = NovaPoshtaApi(\"API_KEY\", async_mode=True)\nfrom novaposhta.chains import Chain\naddress = client.address\nchain = (\n    Chain(\n        address.search_settlements,\n        kwargs={'city_name': 'Київ'},\n        prepare_next=lambda x: {'settlement_ref': x['data'][0]['Ref']}\n    ) |\n    Chain(\n        address.search_settlement_streets,\n        kwargs={'street_name': 'Main'}\n    )\n)\n\n# Execute and process results\nresults = await chain.execute_async()\nfor result in results:\n    print(f\"Success: {result.success}\")\n    print(f\"Data: {result.data}\")\n    print(f\"Next kwargs: {result.next_kwargs}\")\n```\n\n### Limitations\n\n- Currently optimized for async usage\n- Experimental API that may change\n- Sequential execution only (no parallel operations)\n\n\n\n## Testing and linting\nNote: install dev dependencies first\n```bash\npoetry run black novaposhta/\npoetry run isort novaposhta/\npoetry run mypy novaposhta/\npoetry run pytest --cov=novaposhta tests/\n```\n\n## Contributing\n\nWe welcome contributions that can help in enhancing the functionality and improving the consistency of the client. For\nbugs or feature requests, please open an issue on the GitHub repository.\nPlease, use `black`, `isort` and `mypy` as your instrument for code formatting and type checking.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsemolex%2Fnovaposhta-python-client","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsemolex%2Fnovaposhta-python-client","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsemolex%2Fnovaposhta-python-client/lists"}