---
title: "Generate Meta Ads targeting circles"
method: GET
path: "/v1/data/targeting/meta"
tags: ["Targeting"]
---

# Generate Meta Ads targeting circles

`GET /v1/data/targeting/meta`

## Request

- Base URL: `https://api.mapulus.com`
- URL: `https://api.mapulus.com/v1/data/targeting/meta`
- Auth: HTTP bearer

Generate Meta Ads targeting circles from boundary polygons.

Decomposes one or more statistical boundaries into a set of inclusion
(positive) and exclusion (negative) circles that approximate the boundary
shape for use with Meta Ads Manager custom location targeting.

**Caching:** Results are cached by boundary hash. Repeat requests return
instantly from cache regardless of boundary size. Pass `nocache=true` to
force recomputation.

**Async for large boundaries:** Boundaries with total area > 100 km² are
automatically offloaded to a background worker. The endpoint returns 202
with a `poll_url` to check progress.

**How it works:**

1. Fetches and unions the requested boundary geometries
2. Analyses shape complexity (concavity ratio)
3. Auto-sizes the circle radius based on total area and complexity
4. Generates inclusion circles via grid sampling inside the boundary
5. Generates exclusion circles for overshoot areas outside the boundary
6. Ensures total circles stay within Meta's 200-location limit

**Output formats:**

- `json` (default): structured response with inclusion/exclusion arrays
- `csv`: downloadable CSV with type, latitude, longitude, radius, distance_unit columns

**Limits:**

- 1–20 boundary IDs per request
- Combined output capped at 200 circles (Meta's limit)
- Radius range: 1.0–80 km (0.62–50 miles)

## Query parameters

- `boundary_id` string, required: Comma-separated boundary IDs to target (e.g. 'sa2:117011325,lga:17200'). Max 20.
- `radius_unit` 'kilometer' | 'mile': Unit for output radius values.
- `mode` 'circles' | 'postal': Targeting mode: 'circles' (default) or 'postal' (ZIP/postcode inclusion + exclusion circles).
- `format` 'json' | 'csv': Output format: json or csv.
- `nocache` boolean: Skip cache and recompute (dev/debug only).

## Response `200`

Meta Ads targeting circles.

- ResponseEnvelopeMetaTargetingResult
  - `data` MetaTargetingResult, required: Result of Meta Ads targeting circle generation.
    - `mode` string: Targeting mode: 'circles' or 'postal'.
    - `inclusion` MetaCircle[], required: Inclusion (positive) circles.
      - `latitude` number, required: Circle centre latitude.
      - `longitude` number, required: Circle centre longitude.
      - `radius` number, required: Circle radius.
      - `distance_unit` string, required: Radius unit (kilometer or mile).
      - `address` string, nullable: Reverse-geocoded address of circle center.
    - `exclusion` MetaCircle[], required: Exclusion (negative) circles.
      - `latitude` number, required: Circle centre latitude.
      - `longitude` number, required: Circle centre longitude.
      - `radius` number, required: Circle radius.
      - `distance_unit` string, required: Radius unit (kilometer or mile).
      - `address` string, nullable: Reverse-geocoded address of circle center.
    - `postal_targets` MetaPostalTarget[], nullable: Postal inclusion targets (only in postal mode).
      - `key` string, required: Meta Ads key (e.g. 'US:90210' or '2000').
      - `code` string, required: Postal code (e.g. '90210').
      - `name` string, required: Postal area name.
      - `boundary_id` string, required: Mapulus boundary_id (e.g. 'us_zcta:90210').
    - `total_circles` integer, required: Total number of circles (inclusion + exclusion).
    - `inclusion_count` integer, required: Number of inclusion circles.
    - `exclusion_count` integer, required: Number of exclusion circles.
    - `postal_count` integer: Number of postal inclusion targets.
    - `radius_km` number, required: Maximum circle radius used (in km, regardless of output unit).
    - `radius_min_km` number, required: Minimum circle radius used (in km).
    - `boundary_ids` string[], required: Input boundary IDs.
    - `area_km2` number, required: Total area of unioned boundaries in km².
    - `concavity_ratio` number, required: Shape complexity (1.0 = convex, lower = more complex).
  - `meta` ResponseMeta: Response metadata.
    - `request_id` string, nullable
    - `pagination` PaginationMeta: Pagination metadata for list responses.
      - `total` integer, required: Total number of matching records.
      - `limit` integer, required: Maximum records returned per page.
      - `offset` integer, required: Number of records skipped.
      - `has_more` boolean, required: Whether more records exist beyond this page.
    - `demographics` DemographicsMeta: Demographics-specific metadata returned with census data endpoints.
      - `topics_included` string[], required: Topics included in the response.
      - `topics_available` string[]: Additional topics available but not requested.
    - `sources` object, nullable

## Other responses

- `202`: Job created for large boundary (poll for result).
- `422`: Validation Error

---

[API](https://skmtc.dev/mapulus/apis/mapulus-api.md) · [All operations](https://skmtc.dev/mapulus/apis/mapulus-api/llms.txt) · [OpenAPI document](https://skmtc.dev/mapulus/apis/mapulus-api/revisions/b99766fa053f?raw)