# Validate location data

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

This endpoint requires at least 1 query parameter and will check if the parameters and their combinations are valid. Returns information about the location based on the datascope set in the options. Foxentry validator is able not only to evaluate the validity of the inputed information but it also can fix various typos, errors and missing data. Foxentry can also suggest more suitable alternatives to the data sent in query. Please pay attention to the result, resultCorrected and suggestions in the response. Always check result.proposal in the response for a proposed solution by Foxentry how you should process the response in your form or application.

## 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 |
|---|---|---|
| `street` | string or null | Street. |
| `streetWithNumber` | string or null | Street with number. |
| `number.full` | string or null | Full house number. |
| `number.part1` | string or null | First section of house number. |
| `number.part1Number` | string or null | Numerical part of the first section. |
| `number.part1Letter` | string or null | Textual part of the first section. |
| `number.part2` | string or null | Second section of house number. |
| `number.part2Number` | string or null | Numerical part of the second section. |
| `number.part2Letter` | string or null | Textual part of the second section. |
| `city` | string or null | City. |
| `zip` | string or null | ZIP code. |
| `full` | string or null | Full address. |
| `country` | string or null | Country code. Supported formats: alpha2 = CZ, alpha3 = CZE, local = Česká republika, international = Czech republic, localShortened = Česko, internationalShortened = Czechia. |

### request.options

Options that change how the endpoint behaves.

| Field | Type | Description |
|---|---|---|
| `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"`. |
| `resultsLimit` | integer | Limits number of suggestions returned by the endpoint. Default: `10`. |
| `acceptPostOfficeAsCity` | boolean | If true, the postOffice name is accepted as city. For example Thámova 137/16, Praha 8 and Thámova 137/16, Praha 86 would be both valid. Default: `false`. |
| `correctionMode` | string | This option determines how automatic corrections are handled. You can choose between full to allow all corrections, format to fix formatting only, suggestion to return corrected data in suggestions, or none for no corrections to be applied. Quality of data differs between countries, therefore it might be desirable to limit the correction mode in some cases. One of: `full`, `format`, `suggestion`, `none`. Default: `"full"`. |
| `correctionModeCrossCountry` | string | This option determines how automatic corrections are handled when a result from another country matches your query. You can choose between full to allow all corrections, format to fix formatting only, suggestion to return corrected data in suggestions, or none for no corrections to be applied. Quality of data differs between countries, therefore it might be desirable to limit the correction mode in some cases. One of: `full`, `format`, `suggestion`, `none`. Default: `"format"`. |

### 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": {
    "query": {
      "streetWithNumber": "Jeseniova 55",
      "city": "Praha",
      "zip": "13000",
      "country": "CZ"
    },
    "options": {
      "dataScope": "full",
      "resultsLimit": 10,
      "acceptPostOfficeAsCity": true
    },
    "client": {
      "country": "CZ",
      "location": {
        "lat": 50.0628,
        "lon": 13.9271
      }
    }
  }
}
```

## Responses

- `200` Successful response. Examples: `valid`, `invalid`, `invalidWithCorrection`, `invalidWithSuggestion`, `countryInternationalFormat`, `countryInternationalShortenedFormat`, `countryLocalFormat`, `countryLocalShortenedFormat`, `correctionModeFormat`, `correctionModeFormatCorrected`, `correctionModeCrossCountryFormat`, `correctionModeCrossCountryFull`
- `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