# Localization

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

Foxentry allows you to check an area with GPS radius in order to return all the addresses within that area. It can also give you additional information about the addresses based on the dataScope option. Please pay attention to the singleLocationResultDistance option, which determines the radius of the search area in meters.

## 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 |
|---|---|---|
| `lat` | number | Latitude of the searched point. |
| `lon` | number | Longitude of the searched point. |

### 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"`. |
| `radius` | integer | Radius of the search area in meters. In other words the distance in meters from the user's GPS coordinates. The number of suggested addresses depends on the size of the radius. If there are too many suitable addresses, the result count is limited by the resultsLimit option. Default: `50`. |
| `acceptNearest` | boolean | If the searched area does not contain any addreses, Foxentry can return list of the Nearest locations to the searched area (acceptNearest = true). Default: `false`. |

### request.client

Information about your user, to make results more relevant.

| Field | Type | Description |
|---|---|---|
| `ip` | string |  |
| `country` | string | Country code in format ISO-3166-1 alpha-2. |

### Example

```json
{
  "request": {
    "query": {
      "lat": 50.0919999,
      "lon": 14.4527403
    },
    "options": {
      "dataScope": "full",
      "dataSource": [
        "CZ",
        "SK",
        "PL"
      ],
      "zipFormat": false,
      "countryFormat": "alpha2",
      "cityFormat": "basic",
      "radius": 50,
      "acceptNearest": false
    }
  }
}
```

## Responses

- `200` Successful response. Examples: `localizationResults`
- `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