This API provides **real-time Facebook Ads audience reach estimates** based on **location, radius, age, and gender**. It helps marketers and developers plan campaigns with accurate targeting insights.

Getting Started

To begin using this API, follow these steps and make your first API call: **Subscribe to a plan:** Visit our Pricing page and subscribe to one of the plans. You can start with the free BASIC plan if available. **Make your first API call:** Visit the RapidAPI Playground — the **Audience Reach Estimator** endpoint should be selected and displayed on the main panel. Since default query parameter values are set, simply click the blue **“Test endpoint”** button. The JSON response will appear on the right panel. **Documentation and Resources:** Detailed endpoint descriptions, input parameters, and response examples are available in the **Endpoints** tab. Code snippets for popular languages like JavaScript, Python, Java, and Shell are also provided for easy integration. You are ready to go!

Authentication

To authenticate, send the **X-RapidAPI-Host** header along with the **X-RapidAPI-Key** header set to your RapidAPI App API Key (as shown in the endpoint code snippets).

Input Parameters

The following query parameters are supported: **location** (required) City, ZIP code or place name for targeting a specific location. Example: `LaGuardia Community College, NY` **radius** (optional) Radius (in miles) around the ZIP code to calculate audience reach. Default: `10` Example: `15` **age** (optional) Age range of the audience in the format `min - max`. Default: `13-65` Example: `18-35` **gender** (optional) Target audience gender: * `0` = All * `1` = Male * `2` = Female Default: `0`

Response Structure

A successful response returns the estimated number of users matching the targeting criteria: ```json "success": true, "location": { "input": "LaGuardia Community College, NY", "formatted_address": "31-10 Thomson Ave, Long Island City, NY 11101, USA", "latitude": 40.7438046, "longitude": -73.93506359999999, "radius_miles": 15 }, "targeting": { "age_min": 18, "age_max": 40, "gender": "male" }, "reach_estimate": { "users_upper_bound": 3700000 } } ``` If no results are found, the API will return: ```json { "success": false, "message": "No results found! Please try again with correct location." } ```

Endpoints

**POST /audience/reach** * **Request Body Parameters:** `zip`, `radius`, `age`, `gender` * **Response Fields:** `success`, `target`, `estimated_users`, `formatted_message`

Rate Limiting

Each subscription plan defines the maximum number of requests per month and RPS (requests per second). Free plans are limited to **1000 requests per hour**.

Rate Limit Headers

All API responses include: **x-ratelimit-requests-limit:** Total requests allowed. **x-ratelimit-requests-remaining:** Remaining requests. **x-ratelimit-requests-reset:** Seconds until quota resets.

Handling Limits

If rate limits are exceeded, the API returns a **429 Too Many Requests** error: ```json { "message": "Too many requests" } ``` Wait for the reset or upgrade your subscription.

Code Examples

Example in **PHP**: ```php $response = file_get_contents('https://yourapi.com/audience/reach', false, stream_context_create([ 'http' => [ 'method' => 'POST', 'header' => "Content-type: application/x-www-form-urlencoded\r\nX-RapidAPI-Key: YOUR_KEY\r\n", 'content' => http_build_query([ 'location' => '90210', 'radius' => '10', 'age' => '18-35', 'gender' => '1' ]), ], ])); echo $response; ``` Similar snippets are available for **JavaScript, Python, Java, and Shell** in the Endpoints tab.

Common HTTP Status Codes

**400 Bad Request:** Missing or invalid parameters **403 Forbidden:** Invalid API key or no active subscription **404 Not Found:** Invalid endpoint **429 Too Many Requests:** Rate limit exceeded **5XX Server Error:** Temporary server-side issue

Support

For issues or clarification, provide the error code, message, and request context for assistance.

Contact Us

For enterprise usage or high-volume requests: **Email:** [alreadycoded@gmail.com](mailto:alreadycoded@gmail.com) **Website:** [https://www.alreadycoded.com](https://www.alreadycoded.com)