# Get location data

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

Foxentry allows you to get information about location based on the dataScope option. Country and ID parameters are required. You can either choose internal ID, which is assigned by Foxentry or external ID from the data source. CZ external = RUIAN, PL external = Gov data, SK external does not exist.

## 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 |
|---|---|---|
| `country` | string | Country code in format ISO-3166-1 alpha-2. |
| `id` | string | Location ID |

### 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"`. |
| `idType` | string | Internal is assigned by Foxentry. External ID may vary for every supported country. CZ = RUIAN, PL = Government data, SK = no external ID. One of: `internal`, `external`. |

### 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": {
      "country": "CZ",
      "id": "d2ade877-1e95-4a83-baa6-5431ce5b3ca8"
    },
    "options": {
      "idType": "internal",
      "dataScope": "full"
    }
  }
}
```

## Responses

- `200` Successful response. Examples: `getFullDataScopeByInternalID`, `getFullDataScopeByExternalID`
- `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