# Example Queries

If this is your first time using the API please reference the [Quick Start](/documentation/placekey-api/quick-start.md) section to get familiar with getting a `placekey` as a response. The example queries below show how to include optional parameters and return additional Placekey types like `address_placekey` and `building_placekey` as well as additional fields like `confidence_score`.

## Get a Placekey for a POI

Example Request:

{% tabs %}
{% tab title="curl" %}

```bash
curl --location 'https://api.placekey.io/v1/placekey' \
--header 'apikey: {{apikey}}' \
--header 'Content-Type: application/json' \
--data '{
  "query": {
    "location_name": "San Francisco City Hall",
    "street_address": "1 Dr Carlton B Goodlett Pl",
    "city": "San Francisco",
    "region": "CA",
    "postal_code": "94102",
    "iso_country_code": "US",
    "latitude": 37.7793,
    "longitude": -122.4193,
    "place_metadata": {
      "store_id": "1234",
      "phone_number": "1234567890",
      "website": "sfgsa.org",
      "naics_code": "712120",
      "mcc_code": "9399"
    }
  },
  "options": {"fields": ["address_placekey", "building_placekey", "confidence_score"]}
}'
```

{% endtab %}

{% tab title="python" %}

```python
import requests
import json

url = "https://api.placekey.io/v1/placekey"

payload = json.dumps({
  "query": {
    "location_name": "San Francisco City Hall",
    "street_address": "1 Dr Carlton B Goodlett Pl",
    "city": "San Francisco",
    "region": "CA",
    "postal_code": "94102",
    "iso_country_code": "US",
    "latitude": 37.7793,
    "longitude": -122.4193,
    "place_metadata": {
      "store_id": "1234",
      "phone_number": "1234567890",
      "website": "sfgsa.org",
      "naics_code": "712120",
      "mcc_code": "9399"
    }
  },
  "options": {
    "fields": [
      "address_placekey",
      "building_placekey",
      "confidence_score"
    ]
  }
})
headers = {
  'apikey': '{{apikey}}',
  'Content-Type': 'application/json'
}

response = requests.post(url, headers=headers, data=payload)
print(response.text)
```

{% endtab %}
{% endtabs %}

Example Response:

```json
{
  "query_id": "0",
  "placekey": "1vqew7z3sv@5vg-7gq-tvz",
  "address_placekey": "03ho5zb3wz@5vg-7gq-tvz",
  "building_placekey": "03ho5zb3wz@5vg-7gq-tvz",
  "confidence_score": "MEDIUM"
}
```

## Get a Placekey for an Address

Example Request:

{% tabs %}
{% tab title="curl" %}

```bash
curl --location 'https://api.placekey.io/v1/placekey' \
--header 'apikey: {{apikey}}' \
--header 'Content-Type: application/json' \
--data '{
  "query": {
    "street_address": "1543 Mission Street, Floor 3",
    "city": "San Francisco",
    "region": "CA",
    "postal_code": "94105",
    "iso_country_code": "US",
    "latitude": 37.7371,
    "longitude": -122.44283
  },
  "options": {"fields": ["building_placekey", "confidence_score", "upi", "parcel", "geoid"]}
}'
```

{% endtab %}

{% tab title="python" %}

```python
import requests
import json

url = "https://api.placekey.io/v1/placekey"

payload = json.dumps({
  "query": {
    "street_address": "1543 Mission Street, Floor 3",
    "city": "San Francisco",
    "region": "CA",
    "postal_code": "94105",
    "iso_country_code": "US",
    "latitude": 37.7371,
    "longitude": -122.44283
  },
  "options": {
    "fields": [
      "building_placekey",
      "confidence_score",
      "upi",
      "parcel",
      "geoid"
    ]
  }
})
headers = {
  'apikey': '{{apikey}}',
  'Content-Type': 'application/json'
}

response = requests.post(url, headers=headers, data=payload)
print(response.text)
```

{% endtab %}
{% endtabs %}

Example Response:

```json
{
  "query_id": "0",
  "placekey": "22g@5vg-7gq-5mk",
  "building_placekey": "22g@5vg-7gq-5mk",
  "confidence_score": "HIGH",
  "upi": "urn:reso:upi:2.0:US:06075:3511080",
  "parcel": "3511080",
  "geoid": "06075"
}
```

## Get a Placekey for a Pair of Coordinates

Example Request:

{% tabs %}
{% tab title="curl" %}

```bash
curl --location 'https://api.placekey.io/v1/placekey' \
--header 'apikey: {{apikey}}' \
--header 'Content-Type: application/json' \
--data '{
    "query": {
        "latitude": 37.7371,
        "longitude": -122.44283
    }
}'
```

{% endtab %}

{% tab title="python" %}

```python
import requests
import json

url = "https://api.placekey.io/v1/placekey"

payload = json.dumps({
  "query": {
    "latitude": 37.7371,
    "longitude": -122.44283
  }
})
headers = {
  'apikey': '{{apikey}}',
  'Content-Type': 'application/json'
}

response = requests.post(url, headers=headers, data=payload)
print(response.text)
```

{% endtab %}
{% endtabs %}

Example Response:

```json
{
  "query_id": "0",
  "placekey": "@5vg-82n-kzz"
}
```

## Get a Placekey with a Geocode

You can request geographic coordinates for the matched address by including `"geocode"` in the `options.fields` array. Each geocode counts as an additional lookup.

Example Request:

{% tabs %}
{% tab title="curl" %}

```bash
curl --location 'https://api.placekey.io/v1/placekey' \
--header 'apikey: {{apikey}}' \
--header 'Content-Type: application/json' \
--data '{
  "query": {
    "street_address": "1201 Grand Street",
    "city": "Hoboken",
    "region": "NJ",
    "postal_code": "07030",
    "iso_country_code": "US"
  },
  "options": {
    "fields": ["geocode"]
  }
}'
```

{% endtab %}

{% tab title="python" %}

```python
import requests
import json

url = "https://api.placekey.io/v1/placekey"

payload = json.dumps({
  "query": {
    "street_address": "1201 Grand Street",
    "city": "Hoboken",
    "region": "NJ",
    "postal_code": "07030",
    "iso_country_code": "US"
  },
  "options": {
    "fields": ["geocode"]
  }
})
headers = {
  'apikey': '{{apikey}}',
  'Content-Type': 'application/json'
}

response = requests.post(url, headers=headers, data=payload)
print(response.text)
```

{% endtab %}
{% endtabs %}

Example Response:

```json
{
  "query_id": "0",
  "placekey": "0o23vyywlq@627-wbk-cwk",
  "geocode": {
    "location": {
      "lat": 40.75242953023465,
      "lng": -74.03258602264596
    },
    "location_type": "RANGE_INTERPOLATED"
  }
}
```

## Get a Placekey with a Custom Query ID

With multiple queries, you can also specify an ID with each query that echoes back.

Example Request:

{% tabs %}
{% tab title="curl" %}

```bash
curl --location 'https://api.placekey.io/v1/placekeys' \
--header 'apikey: {{apikey}}' \
--header 'Content-Type: application/json' \
--data '{
    "queries": [
        {
            "street_address": "1543 Mission Street, Floor 3",
            "city": "San Francisco",
            "region": "CA",
            "postal_code": "94105",
            "iso_country_code": "US"
        },
        {
            "query_id": "thisqueryidaloneiscustom",
            "location_name": "Twin Peaks Petroleum",
            "street_address": "598 Portola Dr",
            "city": "San Francisco",
            "region": "CA",
            "postal_code": "94131",
            "iso_country_code": "US"
        },
        {
            "latitude": 37.7371,
            "longitude": -122.44283
        }
    ]
}'
```

{% endtab %}

{% tab title="python" %}

```python
import requests
import json

url = "https://api.placekey.io/v1/placekeys"

payload = json.dumps({
  "queries": [
    {
      "street_address": "1543 Mission Street, Floor 3",
      "city": "San Francisco",
      "region": "CA",
      "postal_code": "94105",
      "iso_country_code": "US"
    },
    {
      "query_id": "thisqueryidaloneiscustom",
      "location_name": "Twin Peaks Petroleum",
      "street_address": "598 Portola Dr",
      "city": "San Francisco",
      "region": "CA",
      "postal_code": "94131",
      "iso_country_code": "US"
    },
    {
      "latitude": 37.7371,
      "longitude": -122.44283
    }
  ]
})
headers = {
  'apikey': '{{apikey}}',
  'Content-Type': 'application/json'
}

response = requests.post(url, headers=headers, data=payload)
print(response.text)
```

{% endtab %}
{% endtabs %}

Example Response:

```json
[
  {
    "query_id": "0",
    "placekey": "22g@5vg-7gq-5mk"
  },
  {
    "query_id": "thisqueryidaloneiscustom",
    "placekey": "227-223@5vg-82n-pgk"
  },
  {
    "query_id": "2",
    "placekey": "@5vg-82n-kzz"
  }
]
```


---

# 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/example-queries.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.