Pooli API documentation | Swimming pool and spa API | Advanced Swimming Pool Maintenance App

API Overview

Welcome to the Pooli API, a complementary extension to our intuitive Pooli app interface. While the app provides a user-friendly way to manage your pool, our API opens up additional possibilities, enabling advanced interactions with your pool data programmatically. This powerful combination means that you can now automate routine tasks, integrate with other systems, or even create custom applications, all while continuing to enjoy the ease and familiarity of the Pooli app. The Pooli API serves as your versatile gateway to comprehensive and efficient pool management.

Version: 0.1 (Beta) - Date: January 2, 2024

Note: This is a beta version of the Pooli API and may be subject to changes and updates.

Key Features

Programmatic Pool Management: Seamlessly create and delete pools using our API. This feature allows for dynamic management of pool data, offering flexibility and control to automate your pool maintenance and management tasks.
Reading Inventory: Get real-time access to your pool inventory. View available supplies, equipment status, and reorder levels with simple API calls.
Managing To-Dos: Stay on top of your pool maintenance tasks. The API provides functionalities to manage and update your to-do lists, helping you prioritize and schedule maintenance activities efficiently.
Adding Logs: Easily add detailed logs to track pool maintenance, chemical levels, and more. Our API allows for quick log entries, ensuring you have up-to-date information about your pool's condition.
Accessing All Logs: Retrieve comprehensive log data for any specified time range. This feature is ideal for analyzing trends, monitoring pool health over time, and making informed decisions about pool care.

With the Pooli API, you can create custom scripts and applications that leverage these features, streamlining your pool management process and enhancing your pool experience. Our robust, easy-to-use API is designed to empower users, developers, and pool enthusiasts alike to innovate and optimize pool care.

For feature requests, bug reports, or any questions, please email support@pooli.app.

Rate Limiting and Quotas

At Pooli, we have implemented rate limiting to ensure fair and efficient usage of our API. The rate limits vary based on the user's membership status in the Pool Club.

Pool Club Members

Pool Club members enjoy the benefit of unlimited API requests. This privilege allows for more extensive use of the API, facilitating advanced automation, integration, and application development without the concern of hitting usage caps. Discover the huge list of features and benefits of being a Pool Club member and consider signing up to enjoy these advantages.

Non-Club Members

Non-club members are subject to a rate limit of 60 requests per hour. This limit ensures that all users have fair access to the API while preventing excessive use that could impact service quality.

It is important for all users to be aware of these limits to avoid interruptions in service. If you encounter any issues or have questions about our rate limiting policies, please contact support@pooli.app.

Authentication

Securing your data is paramount. Our API uses API keys to authenticate requests. Each key is user-specific, ensuring secure access to your Pooli documents. Follow these steps to authenticate your API requests:

Step 1: Generate Your API Key

Log in to your Pooli Dashboard. Navigate to the API section and generate your unique API key. This key is associated with your account and provides access to your user-specific documents.

Rate Limiting

Rate limiting is applied on a per-user basis to ensure fair usage and system stability. Be mindful of your request frequency to stay within the rate limits.

Using the API Key

Include your API key in every request to the Pooli API. Use the key along with your user ID in the header of your requests as a bearer token.

Versioning

API versions are specified in the url. The current version is v1. For example, to fetch a specific pool, use the following url:


curl -X GET \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
'https://us-central1-pooli-19f1c.cloudfunctions.net/api/v1/users/InubPY9WkGNIWCmg120ixHkFIz63/pools/YOUR_POOL_ID'

Replace YOUR_API_KEY, YOUR_USER_ID, and YOUR_POOL_ID with your actual API key, user ID, and pool ID.

Endpoints

Pooli API endpoints are organized into the following categories:

Pools Endpoints

Manage and retrieve information about pools with these endpoints. They allow you to fetch, create, and delete pool data associated with a specific user.

GET Endpoints

Fetch All Pools

Endpoint: GET /:uid/pools

Description: Retrieves a list of all pools associated with the given user ID (uid). Includes sanitized data.

Parameters: uid (path) - User ID for pool association.
Fetch Specific Pool

Endpoint: GET /:uid/pools/:poolId

Description: Retrieves detailed information about a specific pool associated with the user ID (uid).

Parameters: uid (path) - User ID, poolId (path) - Pool ID.

POST Endpoints

Create Pool
POST Endpoint: Create Pool

Endpoint: POST /:uid/pools

Description: Creates a new pool associated with the given user ID (uid). The pool data must adhere to a specific format, as outlined below.

URL Parameters: uid (path) - User ID.

Body Parameters: The pool parameter is a complex object with the following properties:
```
{
            "name": [String],
            "poolType": ["vinyl", "plaster", "fiberglass", default: "plaster"],
            "filterCategory": ["de", "sand", "cartridge", default: "cartridge"],
            "sanitizingChemical": ["chlorine", "bromine", "swg", "biguanides", "peroxide", "natural", "freshwater"],
            "gallonEstimate": [Number],
            "isIndoor": [Boolean, default: false],
            "supplimentalSanitizers": ["mineral", "ozone", "uv", "ionize", "aop", "enzyme", "unknown", default: []],
}
```
Each property in the pool object has specific data types and constraints. Some properties, such as sanitizingChemical, poolType, filterCategory, and supplimentalSanitizers, are restricted to predefined values as specified in their respective enums.

DELETE Endpoints

Delete Specific Pool

Endpoint: DELETE /:uid/pools/:poolId

Description: Deletes a specific pool identified by poolId for the given user ID (uid).

Parameters: uid (path) - User ID, poolId (path) - Pool ID to be deleted.

Logs Endpoints

These endpoints allow for the management and retrieval of log entries related to pool maintenance, tests, products, and more.

GET Endpoints

Fetch All Logs for a Pool

Endpoint: GET /:uid/pools/:poolId/logs

Description: Retrieves all log entries for a specific pool. Supports pagination and filtering by log type.

Parameters: uid (path), poolId (path), startAfter (query, optional), type (query, optional).
Fetch Specific Log Entry

Endpoint: GET /:uid/pools/:poolId/logs/:logId

Description: Retrieves a specific log entry by its ID for a given pool.

Parameters: uid (path), poolId (path), logId (path).

POST Endpoint

Create Log Entry

Endpoint: POST /:uid/pools/:poolId/logs

Description: Creates a new log entry for a pool. The log structure varies based on the log type.

Parameters: uid (path), poolId (path), type (query), data (body).

Example Request:

curl -X POST \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "chemicalReading": {
      "temp": 78,
      "orp": 500,
      "ph": 7.1,
      "alkalinity": 100,
      "calcium": 250,
      "cyanuricAcid": 50
    }
  }' \
  'https://api.pooli.app/v1/users/{userId}/pools/{poolId}/logs?type=test'

Development Endpoint:

'https://api-dev.pooli.app/v1/users/{userId}/pools/{poolId}/logs?type=test'

DELETE Endpoint

Delete Log Entry

Endpoint: DELETE /:uid/pools/:poolId/logs/:logId

Description: Deletes a specific log entry for a given pool.

Parameters: uid (path), poolId (path), logId (path).

Log Types and Their Fields

The following rules define the required and optional fields for each log type. Common fields for all logs include:

creatorName: string (optional)
createdAt: date (defaults to current date if not provided)
updatedAt: date (optional)

Test Log

Used to record pool chemical and equipment readings.

Type: type=test

scan: object, optional (default: null)
targets: object, optional (as defined by targetParser)
chemicalReading: object, required
- totalChlorine: number, default null
- freeChlorine: number, default null
- totalBromine: number, default null
- peroxide: number, default null
- ph: number, default null
- temp: number, default null
- cyanuricAcid: number, default null
- calcium: number, default null (total hardness - includes magnesium and other minerals)
- cch: number, default null (calcium hardness - calcium content only, always less than total hardness)
- salt: number, default null
- alkalinity: number, default null
- phosphates: number, default null
- totalDissolvedSolids: number, default null
- combinedChlorine: number, default null
- copper: number, default null
- borates: number, default null
- swgProduction: number, default null
- testMethod: string, default null
- biguanide: number, default null
- iron: number, default null
- orp: number, default null
gallonEstimate: number, optional
equipmentReading: object, optional
- otherMethod: string, default null
- swgPercent: number, default null
- observation: string, default null
- filterPressure: number, default null
- testMethod: string, default null

Product Log

Type: type=product

amount: number, default 0
productName: string, required
unitType: string, required
form: string, required
productType: string, required
solution: object, required
- customType: string, default null
- form: string
- name: string
- percent: number, default null
- productType: string

Note Log

Type: type=note

note: string, required
attachments: object, default null

Maintenance Log

Type: type=maintenance

maintenances: array, required
- Each item:
  - name: string
  - category: string
  - duration: number, default null
  - aggregationName: string, optional

Inventory Endpoint

This endpoint allows for retrieving inventory data related to a specific user.

GET Endpoint

Fetch Inventory

Endpoint: GET /:uid/inventory

Description: Retrieves the inventory data associated with the specified user ID (uid).

Parameters: uid (path) - User ID for which the inventory data is to be fetched.

Reminders Endpoint

This endpoint allows for retrieving reminders data related to a specific user.

GET Endpoint

Fetch Reminders

Endpoint: GET /:uid/pools/:poolId/reminders

Description: Retrieves the reminders data associated with the specified user ID (uid) and pool.

Parameters: uid (path) - User ID for which the reminders data is to be fetched, poolId (path),

API Overview

Key Features

Rate Limiting and Quotas

Pool Club Members

Non-Club Members

Authentication

Step 1: Generate Your API Key

Rate Limiting

Using the API Key

Versioning

Endpoints

Pools Endpoints

GET Endpoints

Fetch All Pools

Fetch Specific Pool

POST Endpoints

Create Pool

POST Endpoint: Create Pool

DELETE Endpoints

Delete Specific Pool

Logs Endpoints

GET Endpoints

Fetch All Logs for a Pool

Fetch Specific Log Entry

POST Endpoint

Create Log Entry

DELETE Endpoint

Delete Log Entry

Log Types and Their Fields

Test Log

Product Log

Note Log

Maintenance Log

Inventory Endpoint

GET Endpoint

Fetch Inventory

Reminders Endpoint

GET Endpoint

Fetch Reminders