> ## Documentation Index
> Fetch the complete documentation index at: https://docs.buntinglabs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Search Tags

> Search for OpenStreetMap tags (key and value combinations) by a query.

This endpoint is useful for searching popular OpenStreetMap tags. We
indexed [OpenStreetMap wiki pages](https://wiki.openstreetmap.org/wiki/Main_Page)
for each tag's `description` field
and put them in a vector database.

This makes it easy to search for particular features in English and
get the tag OSM uses for that feature. For example, searching "trail head"
gives `highway=trailhead` as the first result, which is described as:

> A trailhead (`highway=trailhead`) is a designated or customary place where a trip on a trail begins or ends.

Multiple results are returned, ordered in increasing `dist`. This allows for
autocomplete text boxes, where a user can type in their query and then select
the exact tag they want to use.

### Request Parameters

<ParamField query="query" type="string" placeholder="trail head" required>
  The search query that OSM tags and their descriptions will be compared to.

  More information about tags can be found on the [TagInfo](https://taginfo.openstreetmap.org) resource website.
</ParamField>

<ParamField query="api_key" type="string" placeholder="demo" required>
  Your account's API key. You can create an API key by
  [registering for an account](https://buntinglabs.com/account/register)
  and copy and paste it from your [account dashboard](https://buntinglabs.com/dashboard).
</ParamField>

### Response

A successful search query will give a 200 OK response with `Content-Type: application/json`.
Results look like this (query was "national park"):

```json
{
  "tags": [{
    "dist": "0.109221339226",
    "tag_details": {
      "description": "National Park",
      "tag": "protect_class=2"
    }
  }, {
    "dist": "0.116037666798",
    "tag_details": {
      "description": "The boundary of a national park, an area of natural beauty, set aside for conservation and for recreation",
      "tag": "boundary=national_park"
    }
  }]
}
```

In the event of an error, an error response will be issued, usually with a 5xx error code.
The error will be JSON-formatted, with an `error` field describing the cause.

<ResponseField name="error" type="string">
  The error message if the extract request parameters were incorrectly formatted.

  This response field will not be present if the extract succeeds.
</ResponseField>

### Data License

This API serves [OpenStreetMap](https://www.openstreetmap.org/) data, which is
freely available and is licensed under the
[Open Data Commons Open Database License (ODbL)](https://www.openstreetmap.org/copyright).

<RequestExample>
  ```bash cURL
  curl --get 'https://osm.buntinglabs.com/v1/osm/tags' \
       --data "query=trail+head" \
       --data "api_key=demo"
  ```

  ```javascript JavaScript
  const params = new URLSearchParams({
    tags: "query=trail+head",
    api_key: "demo"
  });

  fetch(`https://osm.buntinglabs.com/v1/osm/tags?${params}`)
    .then(response => response.json())
    .then(data => console.log(data));
  ```

  ```python Python
  import requests

  params = {
    "query": "trail head",
    "api_key": "demo"
  }

  response = requests.get("https://osm.buntinglabs.com/v1/osm/tags", params=params)
  print(response.json())
  ```
</RequestExample>

<ResponseExample>
  ```json Response
  {
    "tags": [
      {
        "dist": "0.133251905441",
        "tag_details": {
          "description": "A trailhead is a designated or customary place where a trip on a trail begins or ends.",
          "tag": "highway=trailhead"
        }
      },
      {
        "dist": "0.159177839756",
        "tag_details": {
          "description": "Trail riding rest area",
          "tag": "tourism=trail_riding_rest"
        }
      }
    ]
  }
  ```
</ResponseExample>