Metadata-Version: 2.4
Name: amplitude-data-wrapper
Version: 0.6.2
Summary: python wrapper for using the amplitude analytics and taxonomy APIs
Author-email: Tobias McVey <tobias.mcvey@nav.no>
License-Expression: MIT
Project-URL: Homepage, https://github.com/navikt/amplitude-data-wrapper
Keywords: amplitude
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: aiohttp>=3.13.5
Requires-Dist: requests>=2.32.3
Requires-Dist: tqdm>=4.67.1
Dynamic: license-file

# Amplitude data wrapper

[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)

This is a wrapper for [Amplitude](https://amplitude.com/) APIs. You can use it to query and export data from your account and use the taxonomy API.

Built with [requests](https://requests.readthedocs.io/en/latest/), [aiohttp](https://docs.aiohttp.org/en/stable/) and [tqdm](https://github.com/tqdm/tqdm)

**Why use this package instead of other wrappers?**

This package supports regions and so you can use it with Amplitude accounts in the EU and USA.

This package also supports using a proxy so you can keep your project API keys and API secrets confidential.

## Supported Amplitude APIs and docs

- [Amplitude data wrapper](#amplitude-data-wrapper)
  - [Supported Amplitude APIs and docs](#supported-amplitude-apis-and-docs)
    - [Dashboard Rest API](#dashboard-rest-api)
    - [Async chart downloads](#async-chart-downloads)
    - [Privacy API](#privacy-api)
    - [Cohort API](#cohort-api)
    - [Export API](#export-api)
    - [Taxonomy API](#taxonomy-api)

See examples below and in [example.py](example.py)

Install with

```bash
pip install amplitude-data-wrapper
```

or

```bash
uv add amplitude-data-wrapper
```

### Dashboard Rest API

[Results from an existing chart](https://developers.amplitude.com/docs/dashboard-rest-api#results-from-an-existing-chart)

Get data from EU account by setting `region="eu"`.

```python
import amplitude_data_wrapper.analytics_api as amp

# without proxy
r = amp.get_chart(
    api_key=api_key, secret=api_secret, chart_id=chart_id_eu, region="eu"
)  
r.status_code
r.json() # returns data as json
```

Get data from US account by setting `region="us"`.

```python
r = amp.get_chart(
    api_key=api_key, secret=api_secret, chart_id=chart_id_us, region="us"
)  
r.json() # returns data as json
```

Get data from EU account with a proxy by setting region and proxy using a dictionary.

```python

# with proxy
proxies = {"http": "http://myproxy.example.org/method"}
r = amp.get_chart(api_key, api_secret, chart_id_eu, region="eu", proxy=proxies)
r.status_code  # print status code
```

[Event segmentation](https://developers.amplitude.com/docs/dashboard-rest-api#event-segmentation) lets you export events with segments and filters.

```python
our_event_dict = {
    "event_type": "pageview",
    "group_by": [{"type": "event", "value": "app"}, {"type": "event", "value": "team"}],
}
data = amp.get_event_segmentation(
    api_key=api_key,
    secret=api_secret,
    start="20220601",
    end="20220602",
    event=our_event_dict,
    metrics="uniques",
    interval=1,
    limit=1000,
)
```

[User search](https://developers.amplitude.com/docs/dashboard-rest-api#user-search) lets you search for a user with a specific Amplitude ID, Device ID, User ID, or User ID prefix.

```python
user = amp.find_user(
    user=example_id_eu, 
    api_key=api_key, 
    secret=api_secret,
    region="eu")
```

### Async chart downloads

You can also download chart data asynchronously. This is more efficient when downloading lots of charts at once. See [example-async.py](example-async.py) for an example program.

PS! Since this uses asyncio I recommend running asynchronous requests as a separate program, not from a jupyter notebook.

### Privacy API

Delete user data with a [deletion job](https://developers.amplitude.com/docs/user-deletion#deletion-job)

```python
deleteme = amp.delete_user_data(
    user["matches"][0]["amplitude_id"],
    email=email,
    api_key=api_key,
    secret=api_secret,
    region="eu",
    ignore_invalid_id=True,
    delete_from_org=False,
)
```

[Get a list of deletion jobs](https://developers.amplitude.com/docs/user-deletion#get)

```python
tobe_deleted = amp.get_deletion_jobs(
    start="2022-06-01",
    end="2022-07-01",
    api_key=api_key,
    secret=api_secret,
    region="eu",
)
```

### Cohort API

[Getting one cohort](https://developers.amplitude.com/docs/behavioral-cohorts-api#getting-one-cohort)

```python
proxies = {"http": "http://myproxy.domain.org/path"}
file_path = "path-to/cohortdata.csv"
kull = amp.get_cohort(
    api_key,
    api_secret,
    cohort_id,
    filename=file_path,
    props=1,
    region="eu",
    proxy=proxies,
)
```

### Export API

[Export API - Export your project's event data](https://developers.amplitude.com/docs/export-api#export-api---export-your-projects-event-data)

```python
start = "20220601T00"
end = "20220601T01"
data = amp.export_project_data(
    start=start,
    end=end,
    api_key=api_key,
    secret=api_secret,
    filename="path-to/projectdata_eu.zip",
    region="eu",
)
```

### Taxonomy API

[Get all event types](https://developers.amplitude.com/docs/taxonomy-api#get-all-event-types)

```python
types = amp.get_all_event_types(
    api_key=api_key, 
    secret=api_secret, 
    region="eu")
```
