Get Geo-Targeting Options

Returns a paginated list of geographic targeting options. Results can be filtered by type (country, state, city, metro), parent ISO code, country, state, free-text search, or specific ISO code. Supports bulk export in JSON or CSV format. When export=true, the response is streamed as a file attachment in batches of 20,000 records.

Geo-Target Hierarchy

Geo-targets are organized in a four-level hierarchy. When targeting below the country level, you must scope your request using the appropriate parent filter so the API knows which parent to look under.

Level	Type	Parent Type	How to scope the request
1	`country`	None (top level)	No parent filter needed
2	`state`	`country`	Pass `parent_iso` with the country ISO code (e.g., `parent_iso=US`)
3	`city`	`state`	Pass `parent_iso` with the state ISO code (e.g., `parent_iso=CA`)
3	`metro`	`state`	Pass `parent_iso` with the state ISO code (e.g., `parent_iso=CA`)

Example — fetching each level:

# All countries
GET /v2/meta/geotargeting?type=country

# States within the United States
GET /v2/meta/geotargeting?type=state&parent_iso=US

# Cities within California
GET /v2/meta/geotargeting?type=city&parent_iso=CA

# Metro areas within California
GET /v2/meta/geotargeting?type=metro&parent_iso=CA

The parent_iso value comes from the iso_code field returned on the parent record. Always retrieve the parent first to get the correct ISO code to use when fetching children.

Endpoint

GET

https://lifeapi.pulsepoint.com/RestApi/v2/meta/geotargeting

Query Parameters

Name	Data Type	Required	Default	Notes
type	ENUM string	no		Geo-target type filter. Valid values: `country`, `state`, `city`, `metro`
parent_iso	string	no		ISO code of the parent geo-target to scope results (e.g., `US` to get US states)
country	string	no		Country ISO code filter (e.g., `usa`)
state	string	no		State ISO code filter (e.g., `ak`)
search	string	no		Free-text search across geo-target names
iso_code	string	no		Look up a specific geo-target by its ISO code
sort	ENUM string	no		Sort field. Valid values: `sequence`, `name`
order	ENUM string	no	asc	Sort direction. Valid values: `asc`, `desc`
limit	integer	no	50	Maximum number of results per page
cursor	string	no		Opaque pagination cursor. Pass the `next_cursor` value from a previous response to get the next page
export	boolean	no	false	When `true`, triggers file-download mode. Results are streamed in batches of 20,000 records
format	ENUM string	no	json	Export format. Valid values: `json`, `csv`. Only applies when `export=true`

Sample Request

GET https://lifeapi.pulsepoint.com/RestApi/v2/meta/geotargeting?type=state&parent_iso=US&limit=50

Response Field List

Name	Data Type	Notes
success	boolean	Returns `true` on a successful request
message	string	Human-readable result message
requestId	string	Unique identifier for the request
data	array of objects	List of geo-targeting option objects
data.id	integer	Unique identifier of the geo-target
data.name	string	Display name of the geo-target
data.type	string	Geo-target type. One of: `country`, `state`, `city`, `metro`
data.type_id	integer	Numeric identifier for the geo-target type
data.iso_code	string	ISO code of the geo-target. Use this value as `parent_iso` when fetching children of this record
data.has_children	boolean	Whether this geo-target has child entries
data.is_leaf	boolean	Whether this geo-target is a leaf node with no children
data.children_count	integer	Number of child geo-targets
data.path	array of strings	Hierarchy path from root to this geo-target (e.g., `["United States", "California"]`)
data.country_info	object	Country metadata (present for non-country types)
data.country_info.country_iso	string	Country ISO code
data.country_info.country_name	string	Country display name
data.state_info	object	State metadata (present for city and metro types)
data.state_info.state_iso	string	State/province ISO code
data.state_info.state_name	string	State/province display name
pagination	object	Pagination metadata
pagination.limit	integer	The page size used for this response
pagination.total	integer	Total number of records matching the query
pagination.has_more	boolean	Whether additional pages of results exist
pagination.next_cursor	string	Opaque cursor to pass as the `cursor` query parameter to retrieve the next page
pagination.next_cursor_url	string	Full URL for the next page of results

Sample Response

{
  "success": true,
  "message": "Operation completed successfully",
  "requestId": "550e8400-e29b-41d4-a716-446655440000",
  "data": [
    {
      "id": 1234,
      "name": "California",
      "type": "state",
      "type_id": 2,
      "iso_code": "ca",
      "has_children": true,
      "is_leaf": false,
      "children_count": 50,
      "path": ["United States", "California"],
      "country_info": {
        "country_iso": "usa",
        "country_name": "United States"
      },
      "state_info": null
    }
  ],
  "pagination": {
    "limit": 50,
    "total": 51,
    "has_more": true,
    "next_cursor": "eyJpZCI6MTIzNDU2fQ",
    "next_cursor_url": "/RestApi/v2/meta/geotargeting?type=state&parent_iso=US&cursor=eyJpZCI6MTIzNDU2fQ&limit=50"
  }
}

Errors

HTTP Status	Error	Description
400	Validation Error	Invalid query parameters. `export` must be a boolean. `format` must be `json` or `csv`. `type` must be one of the allowed enum values
401	Unauthorized	Invalid or expired access token
422	Unprocessable Entity	Invalid parameter combination. For example, passing `type=country` with a `country` filter is not allowed
429	Too Many Requests	Rate limit exceeded
500	Internal Server Error	Unexpected server error