# Algolia

Algolia is a search and discovery API platform that powers fast, relevant search experiences. The Sling Algolia connector extracts data from the Algolia REST API, supporting indices, settings, rules, synonyms, logs, records, search analytics, click analytics, conversion analytics, and A/B tests.

{% hint style="success" %}
**CLI Pro Required**: APIs require a [CLI Pro token](https://docs.slingdata.io/sling-cli/cli-pro) or [Platform Plan](https://docs.slingdata.io/sling-platform/platform).
{% endhint %}

## Setup

The following credentials and inputs are accepted:

**Secrets:**

* `application_id` **(required)** -> Your Algolia Application ID
* `admin_api_key` **(required)** -> Your Algolia Admin API key (required for full access to all endpoints)
* `region` (optional) -> Analytics API region: `us` (default) or `de`

**Inputs:**

* `analytics_index` **(required for analytics endpoints)** -> The index name to fetch analytics data for (e.g., `my_index`)
* `anchor_date` (optional) -> The starting date for historical analytics data extraction (default: 1 year ago). Format: `YYYY-MM-DD`

### Getting Your API Credentials

1. Log in to the [Algolia Dashboard](https://dashboard.algolia.com/)
2. Go to **Settings** > **API Keys**
3. Copy your **Application ID** and **Admin API Key**

{% hint style="warning" %}
**Important:** The Admin API key is required for access to all endpoints including analytics, rules, synonyms, and logs. The Search API key alone is not sufficient.
{% endhint %}

### Using `sling conns`

{% code overflow="wrap" %}

```bash
sling conns set ALGOLIA type=api spec=algolia secrets='{ application_id: your_app_id, admin_api_key: your_admin_key }' inputs='{ analytics_index: your_index_name }'
```

{% endcode %}

### Environment Variable

See [here](https://docs.slingdata.io/sling-cli/environment#dot-env-file-.env.sling) to learn more about the `.env.sling` file.

{% code overflow="wrap" %}

```bash
export ALGOLIA='{ type: api, spec: algolia, secrets: { application_id: "your_app_id", admin_api_key: "your_admin_key" }, inputs: { analytics_index: "your_index_name" } }'
```

{% endcode %}

### Sling Env File YAML

See [here](https://docs.slingdata.io/sling-cli/environment#sling-env-file-env.yaml) to learn more about the sling `env.yaml` file.

```yaml
connections:
  ALGOLIA:
    type: api
    spec: algolia
    secrets:
      application_id: "your_app_id"
      admin_api_key: "your_admin_key"
    inputs:
      analytics_index: "your_index_name"
```

**For EU analytics region:**

```yaml
connections:
  ALGOLIA:
    type: api
    spec: algolia
    secrets:
      application_id: "your_app_id"
      admin_api_key: "your_admin_key"
      region: "de"
    inputs:
      analytics_index: "your_index_name"
```

## Replication

Here's an example replication configuration to sync Algolia data to a PostgreSQL database:

```yaml
source: ALGOLIA
target: MY_POSTGRES

defaults:
  mode: full-refresh
  object: algolia.{stream_name}

streams:
  # sync all endpoints
  '*':

  # incremental sync for analytics endpoints
  search_count:
    mode: incremental
  click_through_rate:
    mode: incremental
  conversion_rate:
    mode: incremental
  user_count:
    mode: incremental
```

## Endpoints

### Index Management

| Endpoint         | Description                                  | Incremental |
| ---------------- | -------------------------------------------- | ----------- |
| `indices`        | All indices in the application with metadata | No          |
| `index_settings` | Settings configuration for each index        | No          |
| `rules`          | Search rules for each index                  | No          |
| `synonyms`       | Synonyms for each index                      | No          |
| `records`        | All records from each index via browse API   | No          |
| `logs`           | API log entries (last 7 days)                | No          |

### Search Analytics

| Endpoint              | Description                                      | Incremental |
| --------------------- | ------------------------------------------------ | ----------- |
| `top_searches`        | Top search queries with click/conversion metrics | Yes         |
| `search_count`        | Search count aggregated by date                  | Yes         |
| `searches_no_results` | Searches that returned no results                | Yes         |
| `no_results_rate`     | Rate of searches returning no results over time  | Yes         |

### Click Analytics

| Endpoint                 | Description                             | Incremental |
| ------------------------ | --------------------------------------- | ----------- |
| `top_hits`               | Top search results with click analytics | Yes         |
| `searches_no_clicks`     | Searches without any clicks             | Yes         |
| `click_through_rate`     | Click-through rate over time            | Yes         |
| `click_positions`        | Distribution of clicks by position      | Yes         |
| `average_click_position` | Average click position over time        | Yes         |

### Conversion & User Analytics

| Endpoint          | Description                            | Incremental |
| ----------------- | -------------------------------------- | ----------- |
| `conversion_rate` | Conversion rate over time              | Yes         |
| `top_countries`   | Top countries by search count          | Yes         |
| `user_count`      | Unique user count over time            | Yes         |
| `top_filters`     | Top filter attributes used in searches | Yes         |

### A/B Testing

| Endpoint   | Description   | Incremental |
| ---------- | ------------- | ----------- |
| `ab_tests` | All A/B tests | No          |

To discover available endpoints:

```bash
sling conns discover ALGOLIA
```

## Incremental Sync

Analytics endpoints support incremental sync via date range:

* **First run:** Fetches all records from `anchor_date` (default: 1 year ago) to present
* **Subsequent runs:** Only fetches records from the last sync date onward

## Analytics Index

The `analytics_index` input is required for all analytics endpoints (search analytics, click analytics, conversion analytics, user/geo analytics, and filter analytics). Set it to the name of the Algolia index you want to analyze.

If you have multiple indices and want analytics for each, create separate connections with different `analytics_index` values.

## Rate Limiting

The Algolia API has different rate limits per API:

* **Search API:** No fixed per-minute limit (configurable per API key)
* **Analytics API:** 100 requests/minute/application

The connector automatically:

* Uses conservative rate limiting (5 requests/second)
* Retries with exponential backoff on 429 (rate limit) responses
* Retries on 5xx server errors with linear backoff

If you are facing issues connecting, please reach out to us at <support@slingdata.io>, on [discord](https://discord.gg/q5xtaSNDvp) or open a Github Issue [here](https://github.com/slingdata-io/sling-cli/issues).