Source: https://developers.woosmap.com/products/localities/concepts/locality-types/

> For clean Markdown of any page, append `.md` to the page URL.

> For a complete documentation index, see https://developers.woosmap.com/llms.txt

# Locality Types



## Overview

Location types are categories that identify the characteristics of a place. A location can have one or more types
assigned to it.

Types are used in two ways:

- **In responses:** The `types` array indicates what kind of location was returned
- **In requests:** The `types` parameter filters which kinds of locations to return

The `types` parameter is available in [Autocomplete](/products/localities/features/autocomplete/)
and [Geocode](/products/localities/features/geocoding/) APIs.

## Filterable Types

The following main types can be used as values for the `types` parameter
in [Localities Autocomplete](/products/localities/features/autocomplete/) and [Localities Geocode](/products/localities/features/geocoding/)
requests:

| Type                | Description                                                                                                                                                                                     | Coverage                                                                        |
| ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- |
| `address`           | Street addresses with building numbers                                                                                                                                                          | See [Address Coverage](/products/localities/concepts/address-coverage/)         |
| `locality`          | Populated places (cities, towns, villages, hamlets, boroughs, suburbs, quarters, neighbourhoods)                                                                                                | Worldwide                                                                       |
| `postal_code`       | Zip codes and postal codes                                                                                                                                                                      | See [Postal Code Coverage](/products/localities/concepts/postal-code-coverage/) |
| `admin_level`       | Administrative areas (states, regions, departments, provinces, districts)                                                                                                                       | Worldwide                                                                       |
| `country`           | National boundaries and sovereign states                                                                                                                                                        | Worldwide                                                                       |
| `point_of_interest` | Points of interest (landmarks, attractions, businesses) - **Available in [Autocomplete](/products/localities/features/autocomplete/) and [Nearby](/products/localities/features/nearby/) APIs** | Worldwide                                                                       |

For the complete list of all type values and POI categories, see the
[API Reference](/api-reference/localities-api/get-localities-autocomplete/).

### Admin Level Subtypes

When you specify `types=admin_level`, results include these subtypes:

- `admin_level_1` - region, states in most countries
- `admin_level_2` - counties, departments in most countries
- `admin_level_3` - districts in most countries

Use the `excluded_types` parameter to remove unwanted subtypes.

### Locality Subtypes

When you specify `types=locality`, results include these subtypes:

- `city` - Major urban centers
- `town` - Smaller urban areas
- `village` - Small rural communities
- `hamlet` - Very small settlements
- `borough` - Administrative subdivisions of cities
- `suburb` - Residential districts within or near cities
- `quarter` - Named districts within cities
- `neighbourhood` - Local neighborhoods

Use the `excluded_types` parameter to remove unwanted subtypes.

### Point of Interest Types

Points of interest (POIs) include landmarks, attractions, businesses, and other notable locations. POI categories are organized into hierarchical families that allow flexible searching in both [Autocomplete](/products/localities/features/autocomplete/) and [Nearby](/products/localities/features/nearby/) APIs:

- `point_of_interest` - Matches all points of interest
- Parent categories like `business`, `tourism`, `transit.station` - Match all POIs in that family
- Child categories like `business.shop`, `tourism.museum`, `transit.station.airport` - Match specific POI types

Use the `types` parameter for POI category filtering. Combine with `excluded_types` to exclude certain categories.

Examples:

- `types=point_of_interest` - All POIs
- `types=business` - All business POIs
- `types=transit.station.airport` - Airports only
- `types=point_of_interest&excluded_types=business` - All POIs except businesses

See the [API Reference](/api-reference/localities-api/get-localities-autocomplete/) for the complete list of POI types.

## Response Fields and Types

### Deprecated Response Field

The `type` field (singular) is **deprecated** and may be removed in the future. Use the `types` field (plural) instead,
which provides a more complete list of types for each location.

### Response-Only Types

The following types may appear in the `types` array or `address_components` of API responses but **cannot** be used in
the `types` request parameter:

| Type                                          | Description                    | Where It Appears                    |
| --------------------------------------------- | ------------------------------ | ----------------------------------- |
| `route`                                       | Named streets and roads        | Address results, address components |
| `premise`                                     | Building or location names     | Address components                  |
| `division_level_0` through `division_level_3` | Administrative division levels | Address components                  |
| `state`, `county`, `district`                 | Administrative subdivisions    | Address components                  |

## Using Types

### Single Type

```bash
curl "https://api.woosmap.com/localities/autocomplete/?input=paris&types=locality&key=YOUR_KEY"
```

### Multiple Types

Combine types with pipe (`|`):

```bash
curl "https://api.woosmap.com/localities/autocomplete/?input=london&types=locality|postal_code&key=YOUR_KEY"
```

### Exclude Subtypes

Remove unwanted locality subtypes:

```bash
curl "https://api.woosmap.com/localities/autocomplete/?input=downtown&types=locality&excluded_types=neighbourhood&key=YOUR_KEY"
```

## Default Types by Endpoint

| Endpoint                                                    | Default Types                                                     |
| ----------------------------------------------------------- | ----------------------------------------------------------------- | ------------ | -------- |
| [Autocomplete](/products/localities/features/autocomplete/) | `locality                                                         | postal_code` |
| [Geocoding](/products/localities/features/geocoding/)       | `locality                                                         | postal_code  | address` |
| [Details](/products/localities/features/details/)           | All types (based on `public_id`)                                  |
| [Nearby](/products/localities/features/nearby/)             | `point_of_interest` (use `types` parameter to filter by category) |

## Related Documentation

- [Localities Autocomplete](/products/localities/features/autocomplete/)
- [Localities Geocoding](/products/localities/features/geocoding/)
- [Localities Details](/products/localities/features/details/)
- [Localities Nearby](/products/localities/features/nearby/)
- [Tuning Localities Results](/products/localities/guides/tuning-localities-results/)
- [API Reference](/api-reference/localities-api/get-localities-autocomplete/)

## Deprecated POI Types

The following location types are **deprecated** for use in the `types` request parameter. While they may still appear in
API responses for backward compatibility, use `point_of_interest` or specific POI type values in
the [Localities Autocomplete](/products/localities/features/autocomplete/) and [Localities Nearby](/products/localities/features/nearby/) endpoints
for POI filtering.

- `airport` → `transit.station.airport`
- `train_station` → `transit.station.rail`
- `metro_station` → `transit.station`
- `shopping` → `business.shop`
- `museum` → `tourism.museum`
- `art_gallery` → `tourism.art_gallery`
- `tourist_attraction` → `tourism.attraction`
- `amusement_park` → `tourism.attraction.amusement_park`
- `zoo` → `tourism.attraction.zoo`
- `marina` → unsupported