# Localisation and URLs

https://dev.wisecp.com/es/localisation-and-urls

The five endpoints behind the installation's language, currency, time zone and address structure.

## Overview

These five endpoints decide **which language, which currency and which addresses** the installation runs on. They look like small settings, but three of them reach across the whole installation, and this article is largely about those.

The time zone and the date format change safely. The **locale, the currency, the country** and the **address mode** write files, flip tables or create folders; change those on a live installation with care.

## Reference

### Reading the Localisation

get/api/v1/admin/settings/localisation

`Settings/GetLocalisationSettings` admin options included

Returns the installation's language, currency, country and time zone.

Response fields data — 8

languagestringThe default language.

localstringThe default locale. It decides the number and date formats.

currencyintId of the default currency.

countrystringThe default country.

timezonestringThe time zone.

date_formatstringHow dates are displayed.

ip_modulestringThe module that resolves a visitor's location.

availableobjectThe time zones you can pick and the location modules installed. Present on the read only.

Errors 1

insufficient_scope403The key lacks the required scope.

Request cURL JavaScript PHP (HTTP) PHP (Internal)

```bash
curl 'https://panel.example.com/api/v1/admin/settings/localisation' \
  -H "Authorization: Bearer $API_KEY"
```

```javascript
const res  = await fetch('https://panel.example.com/api/v1/admin/settings/localisation', {
  headers: { Authorization: `Bearer ${apiKey}` },
});
const body = await res.json();
```

```php
$ch = curl_init('https://panel.example.com/api/v1/admin/settings/localisation');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => ['Authorization: Bearer ' . $apiKey],
]);

$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```

```php
// The values you can pick come back in the SAME response; no separate reference call is needed.
$loc   = Api::Settings()->GetLocalisationSettings()['data'];
$zones = $loc['available']['timezones'];
```

### Writing the Localisation

put/api/v1/admin/settings/localisation

`Settings/UpdateLocalisationSettings` admin high risk

Applies the settings you send. Three of the fields have side effects across the installation.

Body 8

languagestringThe default language.

localstringThe default locale. Changing it rewrites the language package file.

currencyintId of the default currency. Changing it flips the currency table and starts an exchange rate sync.

countrystringThe default country. Moving away from one particular country switches off the identity number fields.

timezonestringThe time zone.

date_formatstringHow dates are displayed.

ip_modulestringThe location module. It has to be installed.

ip_module_configobjectThe location module's settings. Sent together with the module only.

Response fields data — 8

dataobjectThe settings as they now stand. Same shape as the read endpoint.

Errors 1

insufficient_scope403The key lacks the required scope.

Request cURL JavaScript PHP (HTTP) PHP (Internal)

```bash
curl -X PUT 'https://panel.example.com/api/v1/admin/settings/localisation' \
  -H "Authorization: Bearer $API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"timezone":"America/New_York","date_format":"Y-m-d"}'
```

```javascript
const res = await fetch('https://panel.example.com/api/v1/admin/settings/localisation', {
  method: 'PUT',
  headers: {
    Authorization: `Bearer ${apiKey}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    timezone: 'America/New_York',
    date_format: 'Y-m-d',
  }),
});

const body = await res.json();
```

```php
$ch = curl_init('https://panel.example.com/api/v1/admin/settings/localisation');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST  => 'PUT',
    CURLOPT_HTTPHEADER     => [
        'Authorization: Bearer ' . $apiKey,
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'timezone'    => 'America/New_York',
        'date_format' => 'Y-m-d',
    ]),
]);

$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```

```php
// The time zone and the date format are the SAFE fields; the locale, currency and country are not.
Api::Settings()->UpdateLocalisationSettings([
    'timezone'    => 'America/New_York',
    'date_format' => 'Y-m-d',
]);
```

### Reading the Address Settings

get/api/v1/admin/settings/url

`Settings/GetUrlSettings` admin

Returns how addresses are formed and the path names in each language.

Response fields data — 2

rich_urlstringThe address mode. One of three: clean addresses, plain addresses, and a middle mode.

routesobjectThe path names, keyed by language. In each, a map from route key to path segment.

Errors 1

insufficient_scope403The key lacks the required scope.

Request cURL JavaScript PHP (HTTP) PHP (Internal)

```bash
curl 'https://panel.example.com/api/v1/admin/settings/url' \
  -H "Authorization: Bearer $API_KEY"
```

```javascript
const res  = await fetch('https://panel.example.com/api/v1/admin/settings/url', {
  headers: { Authorization: `Bearer ${apiKey}` },
});
const body = await res.json();
```

```php
$ch = curl_init('https://panel.example.com/api/v1/admin/settings/url');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => ['Authorization: Bearer ' . $apiKey],
]);

$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```

```php
// The path names are per language: the same page opens on a different address in each.
$url = Api::Settings()->GetUrlSettings()['data'];
$en  = $url['routes']['en']['products'];
```

### Changing the Address Mode

put/api/v1/admin/settings/url

`Settings/UpdateUrlSettings` admin affects panel access

Switches addresses between clean and plain, testing the server's support live.

Body 1

rich_urlstringrequiredThe new address mode. Sending the value it already has does nothing, and is safe.

Response fields data — 2

dataobjectThe settings as they now stand. Same shape as the read endpoint. A reply means the live check passed and the new mode is in force; on failure the old one stays.

Errors 2

mod_rewrite_failed422The server does not support clean addresses. The check runs live, and on failure the mode is left alone.

insufficient_scope403The key lacks the required scope.

Request cURL JavaScript PHP (HTTP) PHP (Internal)

```bash
curl -X PUT 'https://panel.example.com/api/v1/admin/settings/url' \
  -H "Authorization: Bearer $API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"rich_url":"on"}'
```

```javascript
const res = await fetch('https://panel.example.com/api/v1/admin/settings/url', {
  method: 'PUT',
  headers: {
    Authorization: `Bearer ${apiKey}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ rich_url: 'on' }),
});

const body = await res.json();
```

```php
$ch = curl_init('https://panel.example.com/api/v1/admin/settings/url');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST  => 'PUT',
    CURLOPT_HTTPHEADER     => [
        'Authorization: Bearer ' . $apiKey,
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode(['rich_url' => 'on']),
]);

$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```

```php
// This endpoint creates or removes the ADMIN FOLDER: a wrong mode can break the panel address.
// Read the current mode first; sending the same value is harmless.
$current = Api::Settings()->GetUrlSettings()['data']['rich_url'];

if ($current !== 'on') {
    Api::Settings()->UpdateUrlSettings(['rich_url' => 'on']);
}
```

### Writing the Path Names

put/api/v1/admin/settings/url/views

`Settings/UpdateUrlViews` admin old addresses break

Writes the path names that appear in page addresses, per language.

Body 1

routesobjectrequiredThe path names, keyed by language. Only route keys that already exist are written; an unknown key is ignored.

Response fields data — 2

dataobjectThe address settings as they now stand. Same shape as the read endpoint.

Errors 1

insufficient_scope403The key lacks the required scope.

Request cURL JavaScript PHP (HTTP) PHP (Internal)

```bash
curl -X PUT 'https://panel.example.com/api/v1/admin/settings/url/views' \
  -H "Authorization: Bearer $API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"routes":{"en":{"products":"products","cart":"cart"}}}'
```

```javascript
const res = await fetch('https://panel.example.com/api/v1/admin/settings/url/views', {
  method: 'PUT',
  headers: {
    Authorization: `Bearer ${apiKey}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    routes: { en: { products: 'products', cart: 'cart' } },
  }),
});

const body = await res.json();
```

```php
$ch = curl_init('https://panel.example.com/api/v1/admin/settings/url/views');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST  => 'PUT',
    CURLOPT_HTTPHEADER     => [
        'Authorization: Bearer ' . $apiKey,
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'routes' => ['en' => ['products' => 'products']],
    ]),
]);

$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```

```php
// Changing a path name breaks the OLD address, the one in search engines and in links people saved.
// Read the keys from the current structure; an invented key is skipped without a word.
$routes = Api::Settings()->GetUrlSettings()['data']['routes'];
$routes['en']['products'] = 'shop';

Api::Settings()->UpdateUrlViews(['routes' => $routes]);
```

## Pitfalls

> **The address mode rebuilds the panel folder**
> 
> Changing the mode **tests live** whether the server supports clean addresses, and creates or removes the admin folder. A wrong mode can leave the panel unreachable. Sending the value it already has does nothing, so reading the current mode first is the safest route.

> **A currency change flips the table**
> 
> Changing the default currency does not merely update a preference: the local flag moves in the currency table and an **exchange rate sync starts**. How prices look changes across the installation. Do not do it during trading hours.

> **The locale rewrites the language file**
> 
> Changing the default locale causes the language package file to be **rewritten**. That is a different kind of act from saving a setting: a file on disk changes. The locale is best set once at installation and left alone.

> **The country can switch off the identity fields**
> 
> Moving the default country away from one particular country **switches off the identity number fields** on the registration form. It is a silent side effect: the form changes though you touched nothing in the client registration settings.

> **Changing a path name breaks the old address**
> 
> Change a page's path name and the old address **stops working**: search engine entries and links clients saved go nowhere, and no redirect is set up. An unrecognised route key is also ignored without a word, so a path you thought you wrote may never have been written. Confirm the result through the read endpoint.

## Related Articles

- [Site Settings](https://dev.wisecp.com/en/site-settings)
- [Client Registration](https://dev.wisecp.com/en/client-registration)