# Search location

`POST https://api.foxentry.com/location/search`

This enpoint mainly serves as autocomplete but can be used to search for specific addresses based on filter criteria as well. Foxentry will automatically offer you suggestions to complete the address you are writing down. Pay attention to the client section in the request body. You can specify the user's location in order to receive more relevant suggestions.

## Headers

| Header | Value |
|---|---|
| `Api-Version` | `2.1` or `2.0` |
| `Authorization` | `Bearer <your API key>` |
| `Content-Type` | `application/json` |

## Request body

### request.query

Parameters you want to validate or search for.

| Field | Type | Description |
|---|---|---|
| `type` | string | Type of search. One of: `street`, `streetWithNumber`, `number.full`, `number.part1`, `number.part2`, `city`, `zip`, `full`. |
| `value` | string | Searched value. |
| `filter.street` | string or null | Street. |
| `filter.streetWithNumber` | string or null | Street with number. |
| `filter.number.full` | string or null | Full number. |
| `filter.number.part1` | string or null | First part of the number. |
| `filter.number.part2` | string or null | Second part of the number. |
| `filter.city` | string or null | City. |
| `filter.zip` | string or null | ZIP code. |
| `filter.state` | string or null | Federal state. |
| `filter.region` | string or null | Region. |
| `filter.district` | string or null | District. |
| `filter.country` | string or null | Country code in format ISO-3166-1 alpha-2. |

### request.options

Options that change how the endpoint behaves.

| Field | Type | Description |
|---|---|---|
| `resultsLimit` | integer | Limits number of results returned by the endpoint. Default: `10`. |
| `resultsOffset` | integer | Pagination offset. Available only if the resultsTotal in response is not null. Default: `0`. |
| `allowPartialResults` | boolean | If true, the results can contain streets without number. This might occur when the street is present in multiple cities. Applicable only when using the streetWithNumber or full search types. Default: `true`. |
| `filterMode` | string | Prefer = prefer results matching the filter parameters, limit = limit to results matching the filter parameters. One of: `limit`, `prefer`. Default: `"limit"`. |
| `filterAcceptFormat` | boolean | If true, values with different format would be accepted. (Uppercase and diacritics). Default: `true`. |
| `filterAcceptAlternatives` | boolean | If true, alternative values for filter types would be accepted. For example for City, also CityDistrict and CityDistrictSpecial would be accepted. (Praha, Praha 8, Karlín). Default: `true`. |
| `filterExactMatch` | boolean | If true, only exact match would be accepted. For example "Prah" would return 0 results, since no city with the exact name exists. Default: `true`. |
| `dataScope` | string | Data scope of returned data. One of: `basic`, `full`. Default: `"basic"`. |
| `dataSource` | array[string] | Array of allowed data sources, which restricts countries the module searches. Although we use the request.client object to provide most relevant results, it is generally recommended to to limit this option to only the necessary sources - especially if you don't utilize the request.client object. Default: `["AD", "AL", "AT", "BA", "BE", "BG", "CH", "CY", "CZ", "DE", "DK", "ES", "FR", "GB", "GR", "HR", "HU", "IS", "IT", "LI", "LU", "MC", "ME", "MK", "MT", "NL", "PL", "RO", "RS", "SI", "SK", "SM", "VA", "XK"]`. |
| `zipFormat` | boolean | Whether to return locally formatted ZIP code or not. (130 00 vs 13000). Default: `false`. |
| `countryFormat` | string | This option determines the format in which the country is returned. Choices include local (Česká republika) and international (Czech republic) variants with their shortened counterparts (Česko, Czechia). You can use ISO 3166 alpha codes (CZ, CZE) as well. One of: `alpha2`, `alpha3`, `local`, `localShortened`, `international`, `internationalShortened`. Default: `"alpha2"`. |
| `cityFormat` | string | This option determines the format in which the city is returned. Minimal = Praha, basic = Praha 8, extended = Praha 8 - Karlín. One of: `minimal`, `basic`, `extended`. Default: `"basic"`. |

### request.client

Information about your user, to make results more relevant.

| Field | Type | Description |
|---|---|---|
| `ip` | string |  |
| `country` | string | Country code in ISO-3166-1 alpha-2 format. |
| `location.lat` | number | Client's latitude |
| `location.lon` | number | Client's longitude |

### Example

```json
{
  "request": {
    "customId": "customer567914",
    "query": {
      "type": "streetWithNumber",
      "value": "thamo",
      "filter": {
        "country": "CZ"
      }
    },
    "options": {
      "dataScope": "basic",
      "resultsLimit": 10,
      "filterMode": "prefer",
      "filterAcceptFormat": true,
      "filterAcceptAlternatives": true,
      "filterExactMatch": true
    },
    "client": {
      "ip": "127.0.1.1",
      "country": "CZ",
      "location": {
        "lat": 50.0628,
        "lon": 13.9271
      }
    }
  }
}
```

## Responses

- `200` Successful response. Examples: `searchStreet`, `searchCity`, `searchStreetWithNumber`, `searchStreetWithNumberFederal`, `searchZip`, `searchFull`
- `400` Bad Request
- `401` Unauthorized
- `402` Payment Required
- `403` Forbidden
- `404` Not Found
- `405` Method Not Allowed
- `429` Too Many Requests
- `500` Internal Server Error
- `503` Service Unavailable