leadfeeder 0.0.2
A Python Wrapper for Leadfeeder's API

<!-- PROJECT SHIELDS -->
[![Build Status][build-shield]]()
[![Contributors][contributors-shield]]()
[![MIT License][license-shield]][license-url]
[![LinkedIn][linkedin-shield]][linkedin-url]

<!-- PROJECT LOGO -->




<!-- TABLE OF CONTENTS -->
## Table of Contents

* [About the Project](#about-the-project)
* [Getting Started](#getting-started)
  * [Prerequisites](#prerequisites)
  * [Installation](#installation)
* [Usage](#usage)
* [Contributing](#contributing)
* [Testing](#testing)
* [License](#license)
* [Contact](#contact)

<!-- ABOUT THE PROJECT -->
## About The Project

[Leadfeeder](https://www.leadfeeder.com/) helps you discover companies that visited your website, by identifying visitors and tracking their behaviour. This Python package allows you to easily connect to Leadfeeder's API and build applications on top of it.

<!-- GETTING STARTED -->
## Getting Started

### Prerequisites

This package only supports Python 3.

### Installation

1. Log in to your Leadfeeder account and [get a free API Token](https://app.leadfeeder.com/settings/api)
2. Install the package
```sh
pip3 install leadfeeder
```

<!-- USAGE EXAMPLES -->
## Usage

Import the package...

```python
from leadfeeder import Leadfeeder
```

... then create an instance of Leadfeeder using your API Token.

```python
API_TOKEN = '31kFml4zvl3cWDKoJwBplLoNRcc1PVRQP443sUnT'
leadfeeder = Leadfeeder(API_TOKEN)
```

### Accounts
#### Get accounts associated with token

```python
from pprint import pprint

accounts = leadfeeder.accounts()
pprint(accounts)
```

Assuming a valid token, you should expect an output similar to:

```sh
[{'attributes': {'name': 'www.somedomain.com',
                 'on_trial': False,
                 'subscription': 'lite',
                 'subscription_addons': [],
                 'timezone': 'America/New_York'},
  'id': '63229',
  'type': 'accounts'},
 {'attributes': {'name': 'www.otherdomain.com',
                 'on_trial': True,
                 'subscription': 'premium',
                 'subscription_addons': ['google_data_studio'],
                 'timezone': 'America/New_York'},
  'id': '66884',
  'type': 'accounts'}]
```

#### Get specific account

```python
account = leadfeeder.account(account_id=accounts[0]['id'])
```

### Custom Feeds
#### Get custom feeds associated with account

```python
custom_feeds = leadfeeder.custom_feeds(account_id=account['id'])
```

#### Get specific custom feed associated with account

```python
custom_feed = leadfeeder.custom_feed(account_id=account['id'],
                                     custom_feed_id=custom_feeds[0]['id'])
```

### Leads
#### Get leads associated with account

```python
from datetime import datetime

leads = leadfeeder.leads(account_id=account['id'],
                         start_date=datetime(2019, 6, 11),
                         end_date=datetime(2019, 6, 11),
                         page_number=1,
                         page_size=10)
```

Both `page_number` and `page_size` are optional arguments, used to control the response's pagination. They default to 1 and 10, respectively.

#### Get specific leads associated with account

```python
lead = leadfeeder.lead(account_id=account['id'],
                       lead_id=custom_feed['id'])
```

### Visits
#### Get visits of lead

```python
lead_visits = leadfeeder.lead_visits(account_id=account['id'],
                                     lead_id=lead['id'],
                                     start_date=datetime(2019, 6, 11),
                                     end_date=datetime(2019, 6, 12),
                                     page_number=1,
                                     page_size=10)
```

#### Get visits of account

```python
visits = leadfeeder.visits(account_id=account['id'],
                           start_date=datetime(2019, 6, 11),
                           end_date=datetime(2019, 6, 11),
                           page_number=1,
                           page_size=10)
```

#### Get visits of leads in a given custom feed

```python
custom_feed_visits = leadfeeder.custom_feed_visits(account_id=account['id'],
                                                   custom_feed_id=custom_feed['id'],
                                                   start_date=datetime(2019, 6, 11),
                                                   end_date=datetime(2019, 6, 11),
                                                   page_number=1,
                                                   page_size=10)
```

### Exports

To export leads in a custom feed, first request the export, then continuously check the status of the export until it is successfully processed.

#### Request an export

```python
custom_feed_export_request = leadfeeder.custom_feed_export_request(account_id=account['id'],
                                                                   custom_feed_id=custom_feed['id'],
                                                                   start_date=datetime(2019, 6, 11),
                                                                   end_date=datetime(2019, 6, 11))
```

#### Get export status

```python
custom_feed_export_status = leadfeeder.custom_feed_export_status(export_id=custom_feed_export_request['id'])
```

If the export is successfully processed, you should expect a response such as:

```sh
{'attributes': {'created_at': '2019-06-12T10:10:54.186+00:00',
                'download_url': 'https://api.leadfeeder.com/download/5c0f0a74-9acc-4094-a638-a639b253b14c.json',
                'status': 'processed',
                'status_url': 'https://api.leadfeeder.com/export-requests/5d05590e-8cfa-11e9-b8cc-6576fb85189c'},
 'id': '5d05590e-8cfa-11e9-b8cc-6576fb85189c',
 'type': 'export_requests'}
```

You can then proceed to download the JSON available at `custom_feed_export_status['attributes']['download_url']`.

For additional information, please access the API's [official documentation](https://docs.leadfeeder.com/api/).

<!-- CONTRIBUTING -->
## Contributing

Any contributions are greatly appreciated.

1. Clone the repository
2. Create a new feature branch (`git checkout -b feature/AmazingFeature`)
3. Commit your changes (`git commit -m 'Add some AmazingFeature`)
4. Push to the branch (`git push origin feature/AmazingFeature`)
5. Open a Pull Request

<!-- TESTING -->
## Testing

Make sure the requirements are satisfied then run `py.test` in the project's root.

<!-- LICENSE -->
## License

Distributed under the MIT License. See `LICENSE` for more information.



<!-- CONTACT -->
## Contact

[![LinkedIn][linkedin-shield]][linkedin-url]





<!-- MARKDOWN LINKS & IMAGES -->
[build-shield]: https://img.shields.io/badge/build-passing-brightgreen.svg?style=flat-square
[contributors-shield]: https://img.shields.io/badge/contributors-1-orange.svg?style=flat-square
[license-shield]: https://img.shields.io/badge/license-MIT-blue.svg?style=flat-square
[license-url]: https://choosealicense.com/licenses/mit
[linkedin-shield]: https://img.shields.io/badge/-LinkedIn-black.svg?style=flat-square&logo=linkedin&colorB=555
[linkedin-url]: https://linkedin.com/in/luigigianni
[product-screenshot]: https://raw.githubusercontent.com/othneildrew/Best-README-Template/master/screenshot.png