# Optional Responses

In addition to getting a `placekey` and a `query_id`, you can request additional fields by including them in the `options.fields` parameter. See the [Example Queries](/documentation/placekey-api/example-queries.md) section for full request examples.

```json
"options": {"fields": ["address_placekey", "building_placekey", "confidence_score", "normalized_address", "geocode", "upi", "geoid", "parcel", "gers"]}
```

| Field                | Type   | Description                                                |
| -------------------- | ------ | ---------------------------------------------------------- |
| `address_placekey`   | string | Placekey for the address without `location_name`           |
| `building_placekey`  | string | Placekey for the address without suite or apartment number |
| `confidence_score`   | string | Match confidence: `HIGH`, `MEDIUM`, or `LOW`               |
| `normalized_address` | object | Structured parsed address components                       |
| `geocode`            | object | Geographic coordinates and precision                       |
| `upi`                | string | RESO Universal Parcel Identifier                           |
| `parcel`             | string | Local parcel number                                        |
| `geoid`              | string | Census geographic identifier                               |
| `gers`               | string | Overture Maps identifier (null if unavailable)             |

## address\_placekey

An `address_placekey` is a subcomponent of a Placekey that has the `location_name` not included in the request.

For the query: Starbucks, 48750 Seminole Dr Ste 105, Cabazon, CA, 92230, the `address_placekey` represents just the Placekey for the address (with no `location_name`): 48750 Seminole Dr Ste 105, Cabazon, CA, 92230

## building\_placekey

A `building_placekey` is a subcomponent of the `address_placekey`. It represents the Placekey for the address without the suite or apartment number.

For the query: Starbucks, 48750 Seminole Dr Ste 105, Cabazon, CA, 92230, the `building_placekey` represents just the Placekey for: 48750 Seminole Dr, Cabazon, CA, 92230

## confidence\_score

A `confidence_score` reflects the level of confidence in the accuracy of the assigned Placekey. Factors such as the quality of input data, the precision of geographical coordinates, and the comprehensiveness of available reference data all contribute to this score. Possible values are `HIGH`, `MEDIUM`, and `LOW`.

Providing more input parameters will generally lead to higher confidence.

## normalized\_address

A `normalized_address` is a structured and parsed representation of an address, ensuring consistency across datasets. It breaks down the address into key components for easier matching and integration with other data sources.

Example response:

```json
"normalized_address": {
  "primary_number": "1543",
  "street_name": "Mission",
  "street_suffix": "St",
  "formatted_street": "Mission St",
  "city": "San Francisco",
  "region": "CA",
  "postal_code": "94103",
  "iso_country_code": "US"
}
```

## geocode

Requesting `geocode` returns geographic coordinates for the matched address. This is useful when you need to place a result on a map or perform spatial analysis. Note that the geocode response uses `lng` (not `longitude`) for the longitude value.

Each geocode request counts as an additional lookup. For example, if your plan includes 10k lookups per day and each request includes a geocode, you can make 5k requests (each consuming 2 lookups).

Example response:

```json
"geocode": {
  "location": {
    "lat": 40.75242953023465,
    "lng": -74.03258602264596
  },
  "location_type": "RANGE_INTERPOLATED"
}
```

The `location_type` field indicates the precision of the geocode:

* **ROOFTOP**: Located within the polygon of the corresponding building at the address.
* **PARCEL**: Located within 20 meters of the corresponding building at the address.
* **APPROXIMATE**: Located at the address but greater than 20 meters from a structure.
* **RANGE\_INTERPOLATED**: Inferred from surrounding addresses on the street.

## Universal Parcel Identifier (UPI)

[Universal Parcel Identifier](https://github.com/RESOStandards/reso-upi) (`upi`) developed by [RESO](https://www.reso.org/) is a standard for a single identifier that includes both parcel numbers and the geographies of the authorities that created them.

Example: `"urn:reso:upi:2.0:US:06075:3511080"`

## Parcel Number

A `parcel` is a unique identifier assigned to a specific piece of land by a local government or tax authority, used to track property ownership, taxation, and legal descriptions.

Example: `"3511080"`

## GEOID

A `geoid` (Geographic Identifier) is a code that uniquely identifies a specific geographic area, such as a census block, tract, county, or state. It is used to link geographic areas to census data or other geographic datasets.

Example: `"06075"`

## GERS

A `gers` is an identifier provided by [Overture Maps](https://overturemaps.org/). You can return `gers` along with a Placekey to join datasets with the Overture Maps open datasets. This field returns `null` if no Overture Maps identifier is available for the location.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.placekey.io/documentation/placekey-api/response/optional-responses.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.