> For the complete documentation index, see [llms.txt](https://docs.placekey.io/documentation/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.placekey.io/documentation/placekey-api/example-queries.md).

# 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"
  }
]
```