# Regions

## Get all regions

> Get the filtered list of regions. The endpoint fully supports paging, sorting and filtering mechanism.  

```json
{"openapi":"3.0.0","info":{"title":"Country Service","version":"0.0.1"},"tags":[{"name":"Regions"}],"servers":[{"url":"https://api.emporix.io"}],"security":[{"OAuth2":[]}],"components":{"securitySchemes":{"OAuth2":{"type":"oauth2","flows":{"clientCredentials":{"tokenUrl":"https://api.emporix.io/oauth/token","scopes":{"country.country_read":"Needed to read countries","country.country_manage":"Needed to manage countries","country.region_read":"Needed to read regions"}}}}},"parameters":{"trait_acceptLanguage_header":{"name":"Accept-Language","in":"header","required":false,"schema":{"type":"string"},"description":"List of language codes acceptable for the response. You can specify factors that indicate which language should be retrieved if the one with a higher factor was not found in the localized fields.\n* If the header is set to a particular language or a list of languages, all localized fields are retrieved as maps with the first matched language only.\n* If the header is set to `*`, all localized fields are retrieved as maps of translations, where the keys are language codes and values are the fields in their respective languages.\n* If the header is empty, localized fields are retrieved in the default language defined in the Configuration Service.\n"},"trait_paged_pageNumber":{"name":"pageNumber","in":"query","description":"The page number to be retrieved where the size of the pages must be specified by the pageSize parameter.\nThe number of the first page is 1.\n","schema":{"default":1,"minimum":1,"type":"integer"}},"trait_paged_pageSize":{"name":"pageSize","in":"query","description":"The number of documents being retrieved on the page.\n","schema":{"default":60,"minimum":1,"type":"integer"}},"trait_XTotalCount_header":{"in":"header","name":"X-Total-Count","required":false,"description":"In order to get information how many entities meet a filter requirements, X-Total-Count header has been introduced. The header is optional and its default value is false. It the header is provided and it is true then total count is returned in the X-Total-Count response header. In both cases (X-Total-Count true, false or not provided), the response body has the same format (array of entities). In other words, the information about total count is returned on demand, depending of an existence of X-Total-Count header in a request. Therefore, the X-Total-Count header is not returned if an API consumer didn’t ask for it.","schema":{"default":false,"type":"boolean"}},"trait_sort":{"in":"query","name":"sort","required":false,"description":"Fields to sort the response data by, following the order of the parameters from left to right.\n\n* Can contain multiple fields in the format: `fieldName:sortDirection`, separated by commas.\n\n* The colon with the sort direction parameter is optional.\n\n* Descending order is used only if the sort direction equals `desc` or `DESC`.\n\n* Ascending order is assumed in all other cases.\n\nWhile sorting by a localized field, the following rules apply:\n\n* If a localized field includes a language code, that language is used.  \n  Example: `name.en:ASC` → English (`en`) is used for sorting the `name` property.  \n  The language suffix takes precedence over the `Accept-Language` header.\n\n* If a localized field does not include a language code, the `Accept-Language` header is used.  \n  Example: `name:ASC` with `Accept-Language: de` → German (`de`) is used for sorting.\n\n* If a localized field has no language code and the `Accept-Language` header contains `*`,  \n  the default language from the configuration service is used.  \n  Example: `name:ASC`, `Accept-Language: *`, default language = `pl` → Polish (`pl`) is used.\n\n* If a localized field has no language code and there is no `Accept-Language` header,  \n  the default language from the configuration service is used.\n","schema":{"type":"string"}},"trait_region_name_query_param":{"name":"name","in":"query","required":false,"schema":{"type":"string"},"description":"Region names. When specified, only regions containing the specified names are returned.\n\n**Important**: See how the `Accept-Language` header influences this parameter:\n  * If The `Accept-Language` header is set to `*`, you need to specify a language in this parameter.\n\n    For example, if the `Accept-Language` header is set to `*` and you want to find English names containing the word \"America\", this parameter should be set to \"name.en=America\"\n\n  * If the `Accept-Language` header is set to a particular language or not specified, you do not need to specify a language in this parameter.\n\n    For example, if the `Accept-Language` header is set to `en` and you want to find names containing the word \"America\", this parameter should be set to \"name=America\"\n\n**Note**: When filtering the results with this field, the `contains` operator is used. The operator is case-insensitive.\n"},"trait_region_code_query_param":{"name":"code","in":"query","required":false,"schema":{"type":"string"},"description":"Region codes. When specified, only regions containing the specified codes are returned.\n\n**Note**: When filtering the results with this field, the `contains` operator is used.\n"},"trait_x-version-header":{"name":"X-Version","in":"header","required":true,"schema":{"type":"string","pattern":"^v[1-9][0-9]?$"},"description":"The X-Version header with value v2 is required for the endpoint."}},"responses":{"GetRegions":{"description":"The request was successful. A list of regions is returned.","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/region"}}}}},"BadRequest_400":{"description":"Request was syntactically incorrect. Details are provided in the response payload.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/errorMessage"}}}},"InternalServiceError_500":{"description":"Internal Service Error occurred.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/errorMessage"}}}}},"schemas":{"region":{"title":"Region","type":"object","properties":{"code":{"type":"string","description":"The region code."},"name":{"description":"The localized name of the region. The value is returned as a map where the key is a language code and the value is a translation for the given language.","type":"object","additionalProperties":{"type":"string"}},"metadata":{"$ref":"#/components/schemas/metadata"}}},"metadata":{"type":"object","properties":{"createdAt":{"description":"Date and time when the document was created.","type":"string"},"modifiedAt":{"description":"Date and time when the document was last modified.","type":"string"},"version":{"minimum":1,"type":"integer","description":"Version of the document."}},"required":["createdAt","modifiedAt","version"]},"errorMessage":{"title":"Error","description":"Schema for API specified errors.","type":"object","properties":{"status":{"description":"Original HTTP error reason.","type":"string"},"code":{"description":"Original HTTP error code, should be consistent with the response HTTP code.","type":"integer"},"message":{"description":"Descriptive error message for debugging.","type":"string"},"details":{"description":"List of problems causing this error.","type":"array","items":{"title":"Error Detail","description":"Schema for specific error cause.","type":"string"}}},"required":["status","code"]}}},"paths":{"/country/{tenant}/regions":{"get":{"summary":"Get all regions","description":"Get the filtered list of regions. The endpoint fully supports paging, sorting and filtering mechanism.  ","parameters":[{"$ref":"#/components/parameters/trait_acceptLanguage_header"},{"$ref":"#/components/parameters/trait_paged_pageNumber"},{"$ref":"#/components/parameters/trait_paged_pageSize"},{"$ref":"#/components/parameters/trait_XTotalCount_header"},{"$ref":"#/components/parameters/trait_sort"},{"$ref":"#/components/parameters/trait_region_name_query_param"},{"$ref":"#/components/parameters/trait_region_code_query_param"},{"$ref":"#/components/parameters/trait_x-version-header"}],"responses":{"200":{"$ref":"#/components/responses/GetRegions"},"400":{"$ref":"#/components/responses/BadRequest_400"},"500":{"$ref":"#/components/responses/InternalServiceError_500"}},"operationId":"GET-country-list-all-regions","tags":["Regions"]}}}}
```

## Retrieving a region

> Retrieves a region by the specified code.

```json
{"openapi":"3.0.0","info":{"title":"Country Service","version":"0.0.1"},"tags":[{"name":"Regions"}],"servers":[{"url":"https://api.emporix.io"}],"security":[{"OAuth2":[]}],"components":{"securitySchemes":{"OAuth2":{"type":"oauth2","flows":{"clientCredentials":{"tokenUrl":"https://api.emporix.io/oauth/token","scopes":{"country.country_read":"Needed to read countries","country.country_manage":"Needed to manage countries","country.region_read":"Needed to read regions"}}}}},"responses":{"GetRegion":{"description":"The request was successful. The requested region is returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/region"}}}},"BadRequest_400":{"description":"Request was syntactically incorrect. Details are provided in the response payload.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/errorMessage"}}}},"NotFound_404":{"description":"The requested resource does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/errorMessage"}}}},"InternalServiceError_500":{"description":"Internal Service Error occurred.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/errorMessage"}}}}},"schemas":{"region":{"title":"Region","type":"object","properties":{"code":{"type":"string","description":"The region code."},"name":{"description":"The localized name of the region. The value is returned as a map where the key is a language code and the value is a translation for the given language.","type":"object","additionalProperties":{"type":"string"}},"metadata":{"$ref":"#/components/schemas/metadata"}}},"metadata":{"type":"object","properties":{"createdAt":{"description":"Date and time when the document was created.","type":"string"},"modifiedAt":{"description":"Date and time when the document was last modified.","type":"string"},"version":{"minimum":1,"type":"integer","description":"Version of the document."}},"required":["createdAt","modifiedAt","version"]},"errorMessage":{"title":"Error","description":"Schema for API specified errors.","type":"object","properties":{"status":{"description":"Original HTTP error reason.","type":"string"},"code":{"description":"Original HTTP error code, should be consistent with the response HTTP code.","type":"integer"},"message":{"description":"Descriptive error message for debugging.","type":"string"},"details":{"description":"List of problems causing this error.","type":"array","items":{"title":"Error Detail","description":"Schema for specific error cause.","type":"string"}}},"required":["status","code"]}},"parameters":{"trait_acceptLanguage_header":{"name":"Accept-Language","in":"header","required":false,"schema":{"type":"string"},"description":"List of language codes acceptable for the response. You can specify factors that indicate which language should be retrieved if the one with a higher factor was not found in the localized fields.\n* If the header is set to a particular language or a list of languages, all localized fields are retrieved as maps with the first matched language only.\n* If the header is set to `*`, all localized fields are retrieved as maps of translations, where the keys are language codes and values are the fields in their respective languages.\n* If the header is empty, localized fields are retrieved in the default language defined in the Configuration Service.\n"},"trait_x-version-header":{"name":"X-Version","in":"header","required":true,"schema":{"type":"string","pattern":"^v[1-9][0-9]?$"},"description":"The X-Version header with value v2 is required for the endpoint."}}},"paths":{"/country/{tenant}/regions/{regionCode}":{"get":{"summary":"Retrieving a region","description":"Retrieves a region by the specified code.","responses":{"200":{"$ref":"#/components/responses/GetRegion"},"400":{"$ref":"#/components/responses/BadRequest_400"},"404":{"$ref":"#/components/responses/NotFound_404"},"500":{"$ref":"#/components/responses/InternalServiceError_500"}},"operationId":"GET-country-retrieve-region","tags":["Regions"],"parameters":[{"$ref":"#/components/parameters/trait_acceptLanguage_header"},{"$ref":"#/components/parameters/trait_x-version-header"}]}}}}
```