[comment]: # translation:outdated

[comment]: # aside:2

[comment]: # ({new-ebcec779})
# Quickstart guide

After you have [installed](/devel/python/installation) zabbix\_utils, you can use it in your script.

This quickstart guide shows you how to:

-   Retrieve the hostname from Zabbix agent.
-   Create a host and a trapper item using Zabbix API.
-   Send a value to the item.

The guide presents the script step by step, explaining each part as it is introduced.
The [complete script](#complete-script) is provided at the end of the page.

The guide also assumes your Zabbix server, agent, and API are running locally.

[comment]: # ({/new-ebcec779})

[comment]: # ({new-7917ae33})
#### Retrieve hostname from Zabbix agent

Start by retrieving the hostname of the system where Zabbix agent is running.
You will need this hostname to create a host using Zabbix API.

1\. Import the `Getter` class from zabbix\_utils.
This class works like [Zabbix get](/manual/concepts/get) and lets you request data from Zabbix agent.

2\. Create a `Getter` instance that connects to the local Zabbix agent at `127.0.0.1` on port `10050`.

3\. Call the `get()` method on the `Getter` instance to request the hostname from Zabbix agent.

-   The `get()` method takes an item key as its parameter and sends a request to Zabbix agent for that item.
-   The `get()` method returns an object, and the hostname is stored inside the `value` attribute of that object.
-   [`system.hostname`](/manual/config/items/itemtypes/zabbix_agent#system.hostname) is a built-in Zabbix agent key that returns the host's name.

```python
from zabbix_utils import Getter

agent = Getter(host='127.0.0.1', port=10050)
hostname = agent.get('system.hostname').value
```

[comment]: # ({/new-7917ae33})

[comment]: # ({new-7bec0e05})
#### Connect and log in to Zabbix API

Next, connect to the Zabbix API.
This lets your script manage Zabbix objects such as hosts and items.

1\. Import the `ZabbixAPI` class from zabbix\_utils.

2\. Create a `ZabbixAPI` instance and provide the URL of your Zabbix web interface.

3\. Call the `login()` method on the `ZabbixAPI` instance and provide your username and password.
The account must have [permission](/manual/web_interface/frontend_sections/users/user_roles#default-permissions) to access Zabbix API.

4\. Call the `logout()` method to close the session after API operations.

```python
from zabbix_utils import ZabbixAPI

api = ZabbixAPI(url='127.0.0.1/zabbix')
api.login(user='Admin', password='zabbix')

# API operations go here

api.logout()
```

[comment]: # ({/new-7bec0e05})

[comment]: # ({new-6f1a3be3})
#### Create host in Zabbix

Now that you have the hostname from Zabbix agent and you're connected to Zabbix API, you can create a new host in Zabbix.

1\. Call the [`host.create()`](/manual/api/reference/host/create) API method on the `ZabbixAPI` instance and provide the host details:

-   `host` - set to the `hostname` variable containing the hostname you retrieved from Zabbix agent.
-   `interfaces` - contains connection details for Zabbix agent that's running on the host.
-   `groups` - contains at least one host group the host should belong to.

2\. Since Zabbix API returns the ID of the newly created host, save this ID in the `host_id` variable for later use.

3\. Print a message to confirm the host was created.

```python
api.host.create(
    host=hostname,
    interfaces=[{
        'type': 1,
        'main': 1,
        'useip': 1,
        'ip': '127.0.0.1',
        'dns': '',
        'port': '10050',
    }],
    groups=[{'groupid': '2'}]
)

host_id = host['hostids'][0]

print(f"Host '{hostname}' created with ID {host_id}")
```

[comment]: # ({/new-6f1a3be3})

[comment]: # ({new-b8e7e66c})
#### Create new item in Zabbix

After creating a host, you can add an item to it.

1\. Define a unique key for the item to be created.

2\. Call the [`item.create()`](/manual/api/reference/item/create) method on the `ZabbixAPI` instance and provide the item details:

-   `hostid` - set to the `host_id` variable containing the ID of the host you just created.
-   `name` - a name for the item.
-   `key_` - set to the `item_key` variable you just defined.
-   `type` - set to `2` ([trapper item](/manual/config/items/itemtypes/trapper)), required to receive values sent from your script in the following steps.
-   `value_type` - set to `3` (numeric unsigned), the type of data this item stores.

3\. Since Zabbix API returns the ID of the newly created item, save this ID in the `item_id` variable for later use.

4\. Print a message to confirm the item was created.

```python
item_key = 'app.myservice.heartbeat'

item = api.item.create(
    hostid=host_id,
    name='App heartbeat',
    key_=item_key,
    type=2,
    value_type=3,
)

item_id = item['itemids'][0]

print(f"Item '{item_key}' created with ID {item_id}")
```

[comment]: # ({/new-b8e7e66c})

[comment]: # ({new-10296181})
#### Send value to host

Now that you've created your host and item, you can send data to it.

1\. Import the `time` class and wait a few seconds before sending the data.
This ensures Zabbix has fully processed your new host and item.

2\. Import the `Sender` class from zabbix\_utils.
This class works like [Zabbix sender](/manual/concepts/sender) and lets your script send data to Zabbix.

3\. Create a `Sender` instance that connects to the local Zabbix server at `127.0.0.1` on port `10051`.

4\. Call the `send_value()` method on the `Sender` instance to send a value to your host's item and provide these details:

-   `hostname` - set to the `hostname` variable containing the hostname you retrieved from Zabbix agent.
-   `item_key` - set to the `item_key` variable you just defined earlier in your script.
-   `1` - the value to send.

4\. Print a message to confirm the value was sent.

```python
import time
time.sleep(10)

from zabbix_utils import Sender

sender = Sender(server='127.0.0.1', port=10051)

response = sender.send_value(hostname, item_key, 1)

print(f"Sender response: {response}")
```

After this code runs successfully, you should see a success message indicating Zabbix received your value:

```bash
Sender response: {"processed": 1, "failed": 0, "total": 1, "time": "0.000151", "chunk": 1}
```

Now you can also check your Zabbix web interface (*Monitoring > [Latest data](/manual/web_interface/frontend_sections/monitoring/latest_data)*) to see the value.

[comment]: # ({/new-10296181})

[comment]: # ({new-3872741b})
#### Complete script

Below is the complete script that combines all the steps: retrieving the hostname, creating the host and item using Zabbix API, and sending data to Zabbix.

```python
import time
from zabbix_utils import Getter, ZabbixAPI, Sender

# Retrieve host name from Zabbix agent
agent = Getter(host='127.0.0.1', port=10050)
hostname = agent.get('system.hostname').value

# Connect and log in to Zabbix API
api = ZabbixAPI(url='127.0.0.1/zabbix')
api.login(user='Admin', password='zabbix')

# Create host in Zabbix
host = api.host.create(
    host=hostname,
    interfaces=[{
        'type': 1,
        'main': 1,
        'useip': 1,
        'ip': '127.0.0.1',
        'dns': '',
        'port': '10050',
    }],
    groups=[{'groupid': '2'}]
)

host_id = host['hostids'][0]

print(f"Host '{hostname}' created with ID {host_id}")

# Create item in Zabbix
item_key = 'app.myservice.heartbeat'

item = api.item.create(
    hostid=host_id,
    name='App heartbeat',
    key_=item_key,
    type=2,
    value_type=3
)

item_id = item['itemids'][0]

print(f"Item '{item_key}' created with ID {item_id}")

# Log out from API
api.logout()

# Wait for Zabbix to process new host
time.sleep(10)

# Send value to host
sender = Sender(server='127.0.0.1', port=10051)
response = sender.send_value(hostname, item_key, 1)

print(f"Sender response: {response}")
```

[comment]: # ({/new-3872741b})