> 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/bulk-api.md).

# Bulk API

If you have a large number of places you want to match, you can send batches using the `/v1/placekeys` endpoint.

> 🚧 Batch size can be no more than 100 at once. All queries in a batch must have the same `iso_country_code`.

You can specify a custom `query_id` with each query that echoes back in the response. The `options` parameter is specified at the top level of the request body and applies to all queries in the batch.

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