Placekey

https://docs.placekey.io
Admin
Placekey API helps match places and addresses across datasets by providing unique identifiers for...
Tokens:16,370
Snippets:135
Trust Score:8.2
Update:4 months ago
Show doc for...
Tokens:
Raw
### Example GET Request with Ask Parameter

Source: https://docs.placekey.io/documentation/placekey-api/response

Demonstrates how to query the documentation dynamically using the 'ask' query parameter in an HTTP GET request.

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

--------------------------------

### Dynamic Documentation Query Example

Source: https://docs.placekey.io/documentation/api-overview/error-codes

To get more information not directly on the page, make an HTTP GET request to the page URL with an 'ask' query parameter.

```http
GET https://docs.placekey.io/documentation/api-overview/error-codes.md?ask=<question>
```

--------------------------------

### Install Placekey Python Library

Source: https://docs.placekey.io/documentation/libraries/python

Install the placekey package from PyPI using pip.

```bash
pip install placekey
```

--------------------------------

### Get Placekeys with Custom Query IDs

Source: https://docs.placekey.io/documentation/placekey-api/example-queries

This example demonstrates how to perform multiple queries in a single request and assign custom IDs to each query for easier tracking. It also shows how to query using latitude and longitude.

```APIDOC
## Get a Placekey with a Custom Query ID

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

### Method
POST

### Endpoint
`/v1/placekeys`

### Request Body
```json
{
    "queries": [
        {
            "street_address": "string",
            "city": "string",
            "region": "string",
            "postal_code": "string",
            "iso_country_code": "string"
        },
        {
            "query_id": "string",
            "location_name": "string",
            "street_address": "string",
            "city": "string",
            "region": "string",
            "postal_code": "string",
            "iso_country_code": "string"
        },
        {
            "latitude": "number",
            "longitude": "number"
        }
    ]
}
```

### Response (Success)
```json
[
  {
    "query_id": "string",
    "placekey": "string"
  }
]
```
```

--------------------------------

### Placekey API Authentication Example

Source: https://docs.placekey.io/documentation/api-overview/authentication

This example demonstrates how to authenticate a POST request to the /v1/placekey endpoint using an API Key in the request header.

```APIDOC
## POST /v1/placekey

### Description
This endpoint is used for Placekey-related operations and requires authentication.

### Method
POST

### Endpoint
https://api.placekey.io/v1/placekey

### Headers
- **Content-Type**: application/json
- **apikey**: Your generated API Key

### Request Example
```bash
curl --location --request POST 'https://api.placekey.io/v1/placekey' \
--header 'apikey: {{apikey}}'
```

### Response
(Response details not specified in the source text)
```

--------------------------------

### Get a Placekey with Geocode

Source: https://docs.placekey.io/documentation/placekey-api/example-queries

This example shows how to request geographic coordinates (latitude and longitude) for a matched address by including 'geocode' in the options.fields array. Each geocode lookup incurs an additional cost.

```APIDOC
## 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.

### Method
POST

### Endpoint
`/v1/placekey`

### Request Body
```json
{
  "query": {
    "street_address": "string",
    "city": "string",
    "region": "string",
    "postal_code": "string",
    "iso_country_code": "string"
  },
  "options": {
    "fields": ["geocode"]
  }
}
```

### Response (Success)
```json
{
  "query_id": "string",
  "placekey": "string",
  "geocode": {
    "location": {
      "lat": "number",
      "lng": "number"
    },
    "location_type": "string"
  }
}
```
```

--------------------------------

### Get Placekey for a POI using curl

Source: https://docs.placekey.io/documentation/placekey-api/example-queries

This example shows how to make a curl request to the Placekey API to get a Placekey for a Point of Interest (POI). It includes optional parameters for place metadata and requests additional fields like address_placekey, building_placekey, and confidence_score.

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

--------------------------------

### Querying Documentation via HTTP GET

Source: https://docs.placekey.io/documentation/placekey-api/input-parameters

Use this method to ask specific questions about the Placekey API documentation. The response includes direct answers and relevant excerpts.

```bash
GET https://docs.placekey.io/documentation/placekey-api/input-parameters.md?ask=<question>
```

--------------------------------

### Get Placekey for an Address using curl

Source: https://docs.placekey.io/documentation/placekey-api/example-queries

This curl example shows how to request a Placekey for a specific street address, including floor information. It also requests additional fields such as building_placekey, confidence_score, upi, parcel, and geoid.

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

--------------------------------

### Get Placekeys with Custom Query IDs (curl)

Source: https://docs.placekey.io/documentation/placekey-api/example-queries

This curl command shows how to send multiple queries in a single request to the Placekey API and assign custom IDs to specific queries for easier tracking. It includes examples of address-based and coordinate-based queries.

```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
        }
    ]
}'
```

--------------------------------

### Querying Documentation Dynamically

Source: https://docs.placekey.io/documentation/welcome/placekey-design

To get more information not directly on the page, make an HTTP GET request to the current page URL with the 'ask' query parameter. The question should be specific and in natural language.

```http
GET https://docs.placekey.io/documentation/welcome/placekey-design.md?ask=<question>
```

--------------------------------

### Query Documentation Dynamically

Source: https://docs.placekey.io/documentation/libraries

To get information not directly present on a page, make an HTTP GET request to the page URL with the 'ask' query parameter. The question should be specific and self-contained.

```http
GET https://docs.placekey.io/documentation/libraries.md?ask=<question>
```

--------------------------------

### Query Documentation Dynamically

Source: https://docs.placekey.io/documentation/api-overview

Use this GET request to query the documentation dynamically with a specific question. The response includes a direct answer and relevant excerpts.

```HTTP
GET https://docs.placekey.io/documentation/api-overview.md?ask=<question>
```

--------------------------------

### Query Documentation Dynamically

Source: https://docs.placekey.io/documentation/welcome

To get information not directly on a page, make an HTTP GET request to the page URL with the 'ask' query parameter. The question should be specific and in natural language.

```HTTP
GET https://docs.placekey.io/documentation/welcome.md?ask=<question>
```

--------------------------------

### Get Placekey for an Address (Python)

Source: https://docs.placekey.io/documentation/placekey-api/quick-start

Use this Python script to get a Placekey for a given street address, city, region, postal code, and country.

```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
  }
})

headers = {
  'apikey': '{{apikey}}',
  'Content-Type': 'application/json'
}

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

--------------------------------

### Get Placekey for Coordinates (Python)

Source: https://docs.placekey.io/documentation/placekey-api/quick-start

Use this Python script to get a Placekey using only latitude and longitude coordinates. The resulting Placekey will only contain the 'Where' part.

```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)
```

--------------------------------

### Query Documentation Dynamically

Source: https://docs.placekey.io/documentation/welcome/placekey-types

You can query this documentation dynamically by performing an HTTP GET request on the current page URL with the 'ask' query parameter. The question should be specific, self-contained, and in natural language.

```HTTP
GET https://docs.placekey.io/documentation/welcome/placekey-types.md?ask=<question>
```

--------------------------------

### Get Placekey with Geocode (Python)

Source: https://docs.placekey.io/documentation/placekey-api/example-queries

This Python script demonstrates how to make a POST request to the Placekey API to get a Placekey and its associated geocode. It includes setting the API key and request payload.

```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)
```

--------------------------------

### Get Placekey for a POI (Python)

Source: https://docs.placekey.io/documentation/placekey-api/quick-start

Use this Python script to get a Placekey for a Point of Interest (POI) including location name and metadata.

```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"
    }
  }
})
headers = {
  'apikey': '{{apikey}}',
  'Content-Type': 'application/json'
}

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

--------------------------------

### Get Placekey for a POI (curl)

Source: https://docs.placekey.io/documentation/placekey-api/quick-start

Use this cURL command to get a Placekey for a Point of Interest (POI) including location name and metadata.

```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" \
    } \
  } \
}'
```

--------------------------------

### POST /v1/placekeys

Source: https://docs.placekey.io/documentation/placekey-api/bulk-api

Submit a batch of place queries to the Placekey API to get Placekeys for multiple locations efficiently. The batch size is limited to 100 queries, and all queries must share the same `iso_country_code`.

```APIDOC
## POST /v1/placekeys

### Description
Submit a batch of place queries to the Placekey API to get Placekeys for multiple locations efficiently. The batch size is limited to 100 queries, and all queries must share the same `iso_country_code`.

### Method
POST

### Endpoint
https://api.placekey.io/v1/placekeys

### Parameters
#### Request Body
- **queries** (array) - Required - An array of query objects. Each object can contain:
  - **query_id** (string) - Optional - A custom identifier for the query, which will be echoed back in the response.
  - **street_address** (string) - Optional - The street address of the location.
  - **city** (string) - Optional - The city of the location.
  - **region** (string) - Optional - The state or region of the location.
  - **postal_code** (string) - Optional - The postal code of the location.
  - **iso_country_code** (string) - Required - The ISO 3166-1 alpha-2 country code (e.g., "US", "CA"). All queries in a batch must have the same country code.
  - **latitude** (number) - Optional - The latitude coordinate of the location.
  - **longitude** (number) - Optional - The longitude coordinate of the location.
  - **location_name** (string) - Optional - The name of the location.
- **options** (object) - Optional - An object containing options that apply to all queries in the batch.

### Request Example
```json
{
    "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
        }
    ]
}
```

### Response
#### Success Response (200)
- **query_id** (string) - The identifier for the query, either custom or auto-generated.
- **placekey** (string) - The Placekey for the matched location.

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

--------------------------------

### Get Placekey for an Address (curl)

Source: https://docs.placekey.io/documentation/placekey-api/quick-start

Use this cURL command to get a Placekey for a given street address, city, region, postal code, and country.

```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 \
  } \
}'
```

--------------------------------

### Get Placekey for Coordinates (curl)

Source: https://docs.placekey.io/documentation/placekey-api/quick-start

Use this cURL command to get a Placekey using only latitude and longitude coordinates. The resulting Placekey will only contain the 'Where' part.

```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 \
    } \
}'
```

--------------------------------

### Requesting Optional Fields in Placekey API

Source: https://docs.placekey.io/documentation/placekey-api/response/optional-responses

Include the desired fields in the 'options.fields' parameter to retrieve additional information beyond the basic Placekey and query_id. This example shows a JSON snippet for the options object.

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

--------------------------------

### Universal Parcel Identifier (UPI) Example

Source: https://docs.placekey.io/documentation/placekey-api/response/optional-responses

Example of a RESO Universal Parcel Identifier (UPI) string, a standard for a single identifier that includes parcel numbers and their associated geographies.

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

--------------------------------

### Get a Placekey for an Address

Source: https://docs.placekey.io/documentation/placekey-api/quick-start

This endpoint allows you to retrieve a Placekey for a given street address, city, region, postal code, and country. Latitude and longitude can also be provided for more precise results.

```APIDOC
## Get a Placekey for an Address

### Description
This endpoint allows you to retrieve a Placekey for a given street address, city, region, postal code, and country. Latitude and longitude can also be provided for more precise results.

### Method
POST

### Endpoint
https://api.placekey.io/v1/placekey

### Parameters
#### Request Body
- **query** (object) - Required - The query object containing address details.
  - **street_address** (string) - Optional - The street address.
  - **city** (string) - Optional - The city.
  - **region** (string) - Optional - The region or state.
  - **postal_code** (string) - Optional - The postal code.
  - **iso_country_code** (string) - Optional - The ISO country code (e.g., US).
  - **latitude** (number) - Optional - The latitude coordinate.
  - **longitude** (number) - Optional - The longitude coordinate.

### Request Example
```json
{
  "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
  }
}
```

### Response
#### Success Response (200)
- **query_id** (string) - The ID of the query.
- **placekey** (string) - The generated Placekey.

#### Response Example
```json
{
  "query_id": "0",
  "placekey": "22g@5vg-7gq-5mk"
}
```
```

--------------------------------

### Get Placekey for an Address using Python

Source: https://docs.placekey.io/documentation/placekey-api/example-queries

This Python script demonstrates how to obtain a Placekey for a given street address using the Placekey API. The request includes optional fields to retrieve building_placekey, confidence_score, upi, parcel, and geoid.

```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)
```

--------------------------------

### Get Placekey Prefix Distance Dictionary

Source: https://docs.placekey.io/documentation/libraries/python

Retrieve a dictionary mapping prefix lengths to an upper bound on the maximal distance between Placekeys with that prefix length. Requires the placekey library to be imported.

```python
pk.get_prefix_distance_dict()
```

--------------------------------

### Parcel Number Example

Source: https://docs.placekey.io/documentation/placekey-api/response/optional-responses

Example of a local parcel number, which is a unique identifier assigned to a specific piece of land by a local government for tracking property ownership and taxation.

```string
"3511080"
```

--------------------------------

### Get a Placekey for a Pair of Coordinates

Source: https://docs.placekey.io/documentation/placekey-api/quick-start

Generate a Placekey using only latitude and longitude coordinates. The resulting Placekey will only contain the 'Where' part.

```APIDOC
## Get a Placekey for a Pair of Coordinates

### Description
Generate a Placekey using only latitude and longitude coordinates. The resulting Placekey will only contain the 'Where' part.

### Method
POST

### Endpoint
https://api.placekey.io/v1/placekey

### Parameters
#### Request Body
- **query** (object) - Required - The query object containing coordinates.
  - **latitude** (number) - Required - The latitude coordinate.
  - **longitude** (number) - Required - The longitude coordinate.

### Request Example
```json
{
    "query": {
        "latitude": 37.7371,
        "longitude": -122.44283
    }
}
```

### Response
#### Success Response (200)
- **query_id** (string) - The ID of the query.
- **placekey** (string) - The generated Placekey.

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

--------------------------------

### Get Placekey for a POI using Python

Source: https://docs.placekey.io/documentation/placekey-api/example-queries

This Python script demonstrates how to use the requests library to query the Placekey API for a Point of Interest (POI). It sends a JSON payload with location details and requests specific fields in the response.

```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)
```

--------------------------------

### Get Placekey with Geocode (curl)

Source: https://docs.placekey.io/documentation/placekey-api/example-queries

Use this snippet to request a Placekey for a specific address and include geocoding information in the response. Ensure you have an API key and set the correct content type.

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

--------------------------------

### Query-Level Error Example

Source: https://docs.placekey.io/documentation/api-overview/error-codes

When a query cannot be matched, the API returns an HTTP 200 status but includes an 'error' field in the result for that specific query.

```json
{
  "query_id": "0",
  "error": "Invalid address"
}
```

```json
{
  "query_id": "0",
  "error": "Not enough fields provided"
}
```

--------------------------------

### Get a Placekey for a POI

Source: https://docs.placekey.io/documentation/placekey-api/quick-start

Retrieve a Placekey for a Point of Interest (POI) using its name, address, and optional metadata such as store ID, phone number, website, NAICS code, and MCC code.

```APIDOC
## Get a Placekey for a POI

### Description
Retrieve a Placekey for a Point of Interest (POI) using its name, address, and optional metadata such as store ID, phone number, website, NAICS code, and MCC code.

### Method
POST

### Endpoint
https://api.placekey.io/v1/placekey

### Parameters
#### Request Body
- **query** (object) - Required - The query object containing POI details.
  - **location_name** (string) - Optional - The name of the location.
  - **street_address** (string) - Optional - The street address.
  - **city** (string) - Optional - The city.
  - **region** (string) - Optional - The region or state.
  - **postal_code** (string) - Optional - The postal code.
  - **iso_country_code** (string) - Optional - The ISO country code (e.g., US).
  - **latitude** (number) - Optional - The latitude coordinate.
  - **longitude** (number) - Optional - The longitude coordinate.
  - **place_metadata** (object) - Optional - Metadata about the place.
    - **store_id** (string) - Optional - The store ID.
    - **phone_number** (string) - Optional - The phone number.
    - **website** (string) - Optional - The website URL.
    - **naics_code** (string) - Optional - The NAICS code.
    - **mcc_code** (string) - Optional - The MCC code.

### Request Example
```json
{
  "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"
    }
  }
}
```

### Response
#### Success Response (200)
- **query_id** (string) - The ID of the query.
- **placekey** (string) - The generated Placekey.

#### Response Example
```json
{
  "query_id": "0",
  "placekey": "1vqew7z3sv@5vg-7gq-tvz"
}
```
```

--------------------------------

### Initialize Placekey API Client

Source: https://docs.placekey.io/documentation/libraries/python

Initialize the `PlacekeyAPI` client with your API key. The client includes automatic rate limiting for API requests.

```python
from placekey.api import PlacekeyAPI
placekey_api_key = "..."
pk_api = PlacekeyAPI(placekey_api_key)
```

--------------------------------

### Query Documentation Dynamically

Source: https://docs.placekey.io/documentation/placekey-api

Use this method to ask questions about the documentation. The response will contain a direct answer and relevant excerpts.

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

--------------------------------

### Querying Documentation Dynamically

Source: https://docs.placekey.io/documentation/placekey-api/input-parameters/optional-parameters

Use this method to ask questions about the documentation. The question should be specific and self-contained. The response will include a direct answer and relevant excerpts.

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

--------------------------------

### Send Batch Placekey Queries using Python

Source: https://docs.placekey.io/documentation/placekey-api/bulk-api

This Python script demonstrates how to send a batch of place queries to the Placekey API using the requests library. It includes setting the API key, content type, and the JSON payload for the queries. Remember that each batch is limited to 100 queries.

```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)
```

--------------------------------

### Send Batch Placekey Queries using cURL

Source: https://docs.placekey.io/documentation/placekey-api/bulk-api

Use this cURL command to send a batch of place queries to the Placekey API. Ensure your API key and content type are correctly set. The batch size is limited to 100 queries per request.

```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 \
        } \
    ] \
}'
```

--------------------------------

### GEOID Example

Source: https://docs.placekey.io/documentation/placekey-api/response/optional-responses

Example of a Census Geographic Identifier (GEOID), a code that uniquely identifies a specific geographic area like a census block, tract, or county, used for linking to census data.

```string
"06075"
```

--------------------------------

### Convert Placekey to H3 Index

Source: https://docs.placekey.io/documentation/libraries/python

Use the `placekey_to_h3` function to convert a Placekey to its H3 index representation. Requires the placekey library to be imported.

```python
pk.placekey_to_h3('@dvt-smp-tvz')
```

--------------------------------

### Authenticate API Request with API Key

Source: https://docs.placekey.io/documentation/api-overview/authentication

Use this snippet to authenticate your POST requests to the Placekey API. Ensure you replace '{{apikey}}' with your actual API key.

```bash
curl --location --request POST 'https://api.placekey.io/v1/placekey' \
--header 'apikey: {{apikey}}'
```

--------------------------------

### Lookup Placekey for a Single Location by Coordinates

Source: https://docs.placekey.io/documentation/libraries/python

Use the `PlacekeyAPI.lookup_placekey` method with latitude and longitude to find the Placekey for a specific location. Requires an initialized `PlacekeyAPI` client.

```python
pk_api.lookup_placekey(latitude=37.7371, longitude=-122.44283)
```

--------------------------------

### Placekey API Request Body Parameters

Source: https://docs.placekey.io/documentation/placekey-api/input-parameters

This snippet outlines the structure and available fields for the Placekey API request body. It includes details on location-specific queries and optional response fields.

```APIDOC
## Placekey API Request Body

### Description
This describes the structure of the JSON request body for the Placekey API, detailing the parameters used to define a location and specify desired output fields.

### Parameters
#### Query Parameters
- **query.latitude** (double) - Required - The latitude of the place in WGS-84 coordinates.
- **query.longitude** (double) - Required - The longitude of the place in WGS-84 coordinates.
- **query.location_name** (string) - Optional - The name of the place.
- **query.street_address** (string) - Optional - The street address of the place.
- **query.city** (string) - Optional - The city where the place is located.
- **query.region** (string) - Optional - The second-level administrative region below nation for the place. In the US, this is the state.
- **query.postal_code** (string) - Optional - The postal code for the place.
- **query.iso_country_code** (string) - Optional - The ISO 2-letter Country Code for the place.

#### Place Metadata Parameters
- **query.place_metadata.phone_number** (string) - Optional - The phone number of the POI.
- **query.place_metadata.naics_code** (string) - Optional - 4-digit or 6-digit NAICS code describing the business.
- **query.place_metadata.website** (string) - Optional - The web URL for the POI's publicly available website.
- **query.place_metadata.mcc_code** (string) - Optional - The merchant category code. A four-digit number used by credit card companies to classify businesses.
- **query.place_metadata.store_id** (string) - Optional - The unique ID associated with the store as provided and maintained by the store/brand itself.

#### Other Parameters
- **query_id** (string) - Optional - A custom identifier for this query. Echoed back in the response. Auto-assigned if not provided.
- **options.fields** (array) - Optional - A list of additional fields to include in the response. See [Optional Responses](/documentation/placekey-api/response/optional-responses.md).

### Request Example
```json
{
  "query": {
    "latitude": 37.7371,
    "longitude": -122.44283,
    "city": "San Francisco",
    "region": "California",
    "postal_code": "94105",
    "iso_country_code": "US"
  },
  "query_id": "my-query-1",
  "options": {
    "fields": ["address_placekey", "confidence_score"]
  }
}
```

### Note
In order to return a Placekey some parameters are required. See [Minimum Inputs](/documentation/placekey-api/input-parameters/minimum-inputs.md) for details.
```

--------------------------------

### Calculate Distance Between Two Placekeys

Source: https://docs.placekey.io/documentation/libraries/python

Use the `placekey_distance` function to find the distance in meters between two Placekeys. Requires the placekey library to be imported.

```python
pk.placekey_distance('@dvt-smp-tvz', '@5vg-7gq-tjv')
```

--------------------------------

### Lookup Placekey for a Single Location by Address Details

Source: https://docs.placekey.io/documentation/libraries/python

Use the `PlacekeyAPI.lookup_placekey` method with detailed address information to find the Placekey for a specific location. You can specify which fields to return.

```python
place = {
  "location_name": "Twin Peaks Petroleum",
  "street_address": "598 Portola Dr",
  "city": "San Francisco",
  "region": "CA",
  "postal_code": "94131",
  "iso_country_code": "US"
}
pk_api.lookup_placekey(**place, fields=["building_placekey","address_placekey"])
```

--------------------------------

### Validate Placekey Format

Source: https://docs.placekey.io/documentation/libraries/python

Use the `placekey_format_is_valid` function to check if a given string conforms to the Placekey format. Requires the placekey library to be imported.

```python
pk.placekey_format_is_valid('222-227@dvt-smp-tvz')
```

```python
pk.placekey_format_is_valid('@123-456-789')
```

--------------------------------

### Lookup Placekeys for Multiple Locations

Source: https://docs.placekey.io/documentation/libraries/python

Use the `PlacekeyAPI.lookup_placekeys` method to efficiently retrieve Placekeys for a list of locations. Each location can be specified by coordinates or address details.

```python
places = [
  {
    "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
  }
]
pk_api.lookup_placekeys(places)
```

--------------------------------

### Convert H3 Index to Placekey

Source: https://docs.placekey.io/documentation/libraries/python

Use the `h3_to_placekey` function to convert an H3 index to its corresponding Placekey. Requires the placekey library to be imported.

```python
pk.h3_to_placekey('8a754e64992ffff')
```

--------------------------------

### Error Response

Source: https://docs.placekey.io/documentation/placekey-api/response

Details the structure of error responses from the Placekey API when matching fails.

```APIDOC
## Error Response

### Description
If matching fails, the response will contain an `error` field instead of a `placekey`.

### Response
#### Error Response
- **query_id** (integer) - An ID for this query. If you passed in a `query_id` this will be echoed back to you.
- **error** (object) - An object containing error details. See [Error Codes](/documentation/api-overview/error-codes.md) for details.

#### Response Example
{
  "query_id": 1,
  "error": {
    "error_code": "INVALID_POSTAL_CODE",
    "error_message": "The provided postal code is invalid."
  }
}
```

--------------------------------

### h3_to_placekey

Source: https://docs.placekey.io/documentation/libraries/python

Converts an H3 index to its corresponding Placekey.

```APIDOC
## h3_to_placekey

### Description
Converts a given H3 index into its corresponding Placekey.

### Method
```python
placekey.h3_to_placekey(h3_index)
```

### Parameters
*   **h3_index** (string) - The H3 index to convert.

### Response
*   (string) - The generated Placekey.

### Example
```python
>>> pk.h3_to_placekey('8a754e64992ffff')
'@dvt-smp-tvz'
```
```

--------------------------------

### placekey_to_h3

Source: https://docs.placekey.io/documentation/libraries/python

Converts a Placekey to its corresponding H3 index.

```APIDOC
## placekey_to_h3

### Description
Converts a given Placekey into its corresponding H3 index.

### Method
```python
placekey.placekey_to_h3(placekey)
```

### Parameters
*   **placekey** (string) - The Placekey to convert.

### Response
*   (string) - The H3 index.

### Example
```python
>>> pk.placekey_to_h3('@dvt-smp-tvz')
'8a754e64992ffff'
```
```

--------------------------------

### placekey_distance

Source: https://docs.placekey.io/documentation/libraries/python

Calculates the distance in meters between two Placekeys.

```APIDOC
## placekey_distance

### Description
Calculates the distance in meters between two Placekeys.

### Method
```python
placekey.placekey_distance(placekey1, placekey2)
```

### Parameters
*   **placekey1** (string) - The first Placekey.
*   **placekey2** (string) - The second Placekey.

### Response
*   (float) - The distance in meters.

### Example
```python
>>> pk.placekey_distance('@dvt-smp-tvz', '@5vg-7gq-tjv')
12795124.895573696
```
```

--------------------------------

### Placekey Endpoint Response

Source: https://docs.placekey.io/documentation/placekey-api/response

Describes the JSON response structure when accessing the /placekey endpoint. It includes a `query_id` and the generated `placekey`.

```APIDOC
## GET /placekey

### Description
Returns the Placekey for a given query, along with a query identifier.

### Method
GET

### Endpoint
/placekey

### Parameters
#### Query Parameters
- **query_id** (integer) - Optional - An ID for this query. If passed in, this will be echoed back.
- **options.fields** (string) - Optional - Specifies which optional fields to include in the response. See [Optional Responses](/documentation/placekey-api/response/optional-responses.md) for details.

### Response
#### Success Response (200)
- **query_id** (integer) - An ID for this query. If you passed in a `query_id` this will be echoed back to you.
- **placekey** (string) - The Placekey for the request you make.

#### Response Example
{
  "query_id": 4,
  "placekey": "227-223@5vg-82n-pgk"
}
```
Tokens:
Raw