Guide for Managing Allowed Locations

Allowed Locations as a concept and feature is not applicable to all users. Depending on your contracted agreements, the allowlist endpoint enables you to manage your list of location IDs that are permitted for your account.

The allowlist supports three main operations:

Retrieving your current allowlist (GET)
Adding new location IDs to your allowlist (POST with APPEND)
Removing location IDs from your allowlist (POST with DELETE)
Replacing your entire allowlist (POST with OVERWRITE)

Use Cases

Initial Setup

When first integrating with Terra, you may want to start with a specific set of locations that you've verified are relevant to your use case.

Gradual Expansion

As your integration grows, you can incrementally add new locations to your allowlist without replacing the entire list.

Location Removal

If certain locations are no longer relevant or should be excluded, you can remove them from your allowlist while keeping the rest intact.

Complete Refresh

In some cases, you may need to replace your entire allowlist with a new set of locations.

Getting Started

Prerequisites

Before using the allowlist endpoint, ensure you have:

A valid API key for your account
The API key configured with appropriate permissions
Access to the Partner Services API base URL

Authentication

All allowlist requests require authentication using your API key. Include the API key in the X-API-Key header with every request:

X-API-Key: your-api-key-here

Retrieving Your Allowlist

The GET endpoint allows you to retrieve your current allowlist in a paginated format.

Basic Request

To retrieve the first page of your allowlist (default page size is 1000):

curl -X GET "https://terra.tripadvisor.com/api/allowlist?version=v1" \
  -H "X-API-Key: your-api-key-here"

Operation Types

APPEND

Adds new location IDs to your existing allowlist. Location IDs that already exist in the allowlist will be ignored (no change).

When to use: When you want to add new locations without affecting existing ones.

DELETE

Removes specified location IDs from your allowlist. Location IDs that don't exist in the allowlist will be ignored (no change).

When to use: When you want to remove specific locations while keeping the rest.

OVERWRITE

Replaces your entire allowlist with the provided set of location IDs. All existing locations are removed and replaced with the new set.

When to use: When you want to completely replace your allowlist with a new set of locations.

Rate Limiting

The POST endpoint is subject to rate limiting based on a daily quota per API key. This quota is configured for your account and helps ensure fair usage of the service.

How Rate Limiting Works

Rate limiting applies only to POST requests (GET requests are not rate limited)
The quota is reset daily
Each POST request consumes one quota unit
If you exceed your quota, you'll receive a 429 Too Many Requests response

Checking Your Quota

Your daily quota is configured per API key. Contact support if you need to adjust your quota limits.

Handling Rate Limit Errors

If you receive a 429 Too Many Requests response:

Wait until the next day when your quota resets, or
Contact support to discuss increasing your quota if you have a legitimate need for higher limits