diff --git a/src/api-reference/common/locations/v5.localities.md b/src/api-reference/common/locations/v5.localities.md index 3e706f2a1..3ba033d13 100644 --- a/src/api-reference/common/locations/v5.localities.md +++ b/src/api-reference/common/locations/v5.localities.md @@ -41,6 +41,9 @@ Name| Description |Endpoint `locality.read`| getLocations |`GET ` `locality.read`| getLocationByLocalityId |`GET ` `locality.read`| getSubdivisions |`GET ` +`locality.read`| getSubdivisionByCode |`GET ` +`locality.read`| getAdminRegions |`GET ` +`locality.read`| getAdminRegionById |`GET ` ## Access Token Usage @@ -67,7 +70,7 @@ None #### Payloads * Request: None -* Response: [`CountryListResponse`](#CountryListResponse-schema) +* Response: [`CountryListResponse`](#countrylistresponse-schema) ### Examples @@ -113,7 +116,7 @@ Content-Type: application/json } ``` -## Get Country by Code +## Get Country by Country Code Retrieves country details given a country code. @@ -136,7 +139,7 @@ Name|Type|Format|Description #### Payloads * Request: None -* Response: [`CountryByCodeResponse`](#CountryByCodeResponse-schema) +* Response: [`CountryByCodeResponse`](#countrybycoderesponse-schema) ### Examples @@ -215,7 +218,7 @@ Parameter| Type|Required|Condition|Description #### Payloads * Request: None -* Response: [`LocationListResponse`](#LocationListResponse-schema) +* Response: [`LocationListResponse`](#locationlistresponse-schema) ### Examples @@ -337,7 +340,7 @@ Name|Type|Format|Description #### Payloads * Request: None -* Response: [`LocationDetailsResponse`](#LocationDetailsResponse-schema) +* Response: [`Location`](#location-schema) ### Examples @@ -454,7 +457,7 @@ Name|Type|Format|Description #### Payloads * Request: None -* Response: [`SubdivisionListResponse`](#SubdivisionListResponse-schema) +* Response: [`SubdivisionListResponse`](#subdivisionlistresponse-schema) ### Examples @@ -502,15 +505,278 @@ Content-Type: application/json } ``` +## Get Subdivision by Subdivision Code + +Retrieve subdivision details given country code and subdivision codes. + +### Scopes + +`locality.read` - Refer to [Scope Usage](#scope-usage) for full details. + +#### URI + +```shell +GET https://{region}.api.concursolutions.com/localities/v5/subdivisions/{subdivisionCode} +``` +#### Parameters + +Name|Type|Format|Description +---|---|---|--- +`subdivisionCode`|`string`|-|**Required** ISO 3166-2 Subdivision code. + +#### Payloads + +* Request: None +* Response: [`SubdivisionByCodeResponse`](#subdivisionbycoderesponse-schema) + + +### Examples + +#### Request +```shell +GET https://us2.api.concursolutions.com/localities/v5/subdivisions/AU-QLD +Accept: application/json +Accept-Language: en +Authorization: Bearer ${ACCESS_TOKEN} +``` + +#### Response + +```shell +HTTP/1.1 200 OK +Content-Type: application/json +``` + +```json +{ + "code": "AU-QLD", + "active": true, + "names": [ + { + "name": "Queensland", + "langCode": "en" + } + ], + "countryCode": "AU", + "links": [ + { + "rel": "self", + "href": "https://us2.api.concursolutions.com/localities/v5/subDivisions/AU-QLD" + }, + { + "rel": "country", + "href": "https://us2.api.concursolutions.com/localities/v5/countries/AU" + } + ] +} +``` + +## Get AdminRegions + +Retrieve list of administrative regions given country code and subdivision code. + +### Scopes + +`locality.read` - Refer to [Scope Usage](#scope-usage) for full details. + +#### URI + +```shell +GET https://{region}.api.concursolutions.com/localities/v5/adminRegions?countryCode={countryCode}&subdivisionCode={subdivisionCode} +``` +#### Parameters + +Name|Type|Format|Description +---|---|---|--- +`countryCode`|`string`|-|**Required** Two letter ISO countryCode. +`subdivisionCode`|`string`|-|**Required** ISO 3166-2 Subdivision code. + +#### Payloads + +* Request: None +* Response: [`AdminRegionList`](#adminregionlist-schema) + + +### Examples + +#### Request +```shell +GET https://us2.api.concursolutions.com/localities/v5/adminRegions?countryCode=US&subdivisionCode=US-TX +Accept: application/json +Accept-Language: en +Authorization: Bearer ${ACCESS_TOKEN} +``` + +#### Response + +```shell +HTTP/1.1 200 OK +Content-Type: application/json +``` + +```json +{ + "adminRegions": [ + { + "id": "eb44a08e-0d41-45f4-863a-aa8bb03f90e0", + "active": true, + "names": [ + { + "name": "ANDERSON COUNTY", + "langCode": "en" + } + ], + "country": { + "code": "US", + "links": [ + { + "rel": "self", + "href": "https://us2.api.concursolutions.com/localities/v5/countries/US" + } + ] + }, + "subDivision": { + "code": "US-TX", + "links": [ + { + "rel": "self", + "href": "https://us2.api.concursolutions.com/localities/v5/subdivisions/US-TX" + } + ] + }, + "links": [ + { + "rel": "self", + "href": "https://us2.api.concursolutions.com/localities/v5/adminRegions/eb44a08e-0d41-45f4-863a-aa8bb03f90e0" + } + ] + }, + { + "id": "e9f81fa1-4823-4729-9faf-5f90eb96464c", + "active": true, + "names": [ + { + "name": "ANDREWS COUNTY", + "langCode": "en" + } + ], + "country": { + "code": "US", + "links": [ + { + "rel": "self", + "href": "https://us2.api.concursolutions.com/localities/v5/countries/US" + } + ] + }, + "subDivision": { + "code": "US-TX", + "links": [ + { + "rel": "self", + "href": "https://us2.api.concursolutions.com/localities/v5/subdivisions/US-TX" + } + ] + }, + "links": [ + { + "rel": "self", + "href": "https://us2.api.concursolutions.com/localities/v5/adminRegions/e9f81fa1-4823-4729-9faf-5f90eb96464c" + } + ] + } + ] +} +``` + +## Get AdminRegion by Admin Region Id + +Retrieve administrative region details given Admin Region Id. + +### Scopes + +`locality.read` - Refer to [Scope Usage](#scope-usage) for full details. + +#### URI + +```shell +GET https://{region}.api.concursolutions.com/localities/v5/adminRegions/{adminRegionId} +``` +#### Parameters + +Name|Type|Format|Description +---|---|---|--- +`adminRegionId`|`string`|-|**Required** Valid UUID of the Admin Region. + +#### Payloads + +* Request: None +* Response: [`AdminRegionResponse`](#adminregionresponse-schema) + + +### Examples + +#### Request +```shell +GET https://us2.api.concursolutions.com/localities/v5/adminRegions/3b353fe3-5e4d-4a7a-8230-8eb44db254d0 +Accept: application/json +Accept-Language: en +Authorization: Bearer ${ACCESS_TOKEN} +``` + +#### Response + +```shell +HTTP/1.1 200 OK +Content-Type: application/json +``` + +```json +{ + "id": "3b353fe3-5e4d-4a7a-8230-8eb44db254d0", + "active": true, + "names": [ + { + "name": "ANDERSON COUNTY", + "langCode": "en" + } + ], + "country": { + "code": "US", + "links": [ + { + "rel": "self", + "href": "https://us2.api.concursolutions.com/localities/v5/countries/US" + } + ] + }, + "subDivision": { + "code": "US-TN", + "links": [ + { + "rel": "self", + "href": "https://us2.api.concursolutions.com/localities/v5/subdivisions/US-TN" + } + ] + }, + "links": [ + { + "rel": "self", + "href": "https://us2.api.concursolutions.com/localities/v5/adminRegions/3b353fe3-5e4d-4a7a-8230-8eb44db254d0" + } + ] +} +``` + ## Schemas -### LocationListResponse +### LocationListResponse Name| Type| Format |Description ---|-----|--------------------------------------------------------------------------------|--- -`Locations`| `List` | [`LocationDetailsResponse Schema`](#LocationDetailsResponse-schema) |All active locations for the given company Id. +`Locations`| `List` | [`Location Schema`](#location-schema) |All active locations for the given company Id. -### LocationDetailsResponse +### Location Name| Type | Format |Description ---|-----------|-------------------------------------------------------------------------------|--- @@ -519,104 +785,104 @@ Name| Type | Format `id`| `string` | - |Unique Identifier of the location. `timeZoneOffset`| `integer` | - |Time zone offset of the location (in minutes). `active`| `boolean` | `true`/`false` |Whether the location is active. -`point`| `object` | [`Point Schema`](#Point-schema) |Geographical coordinates of the location. -`names`| `list` | [`LocationName Schema`](#LocationName-schema) |Names for the location. -`administrativeRegion`| `object` | [`AdministrativeRegionResponse Schema`](#AdministrativeRegionResponse-schema) |Administrative region details of the location. -`country`| `object` | [`Code Schema`](#Code-schema) |Country associated with the location. -`subDivision`| `object` | [`Code Schema`](#Code-schema) |Subdivision associated with the location. -`links`| `list` | [`Link Schema`](#Link-schema) |Hateoas links related to the location. +`point`| `object` | [`Point Schema`](#point-schema) |Geographical coordinates of the location. +`names`| `list` | [`LocationName Schema`](#locationname-schema) |Names for the location. +`administrativeRegion`| `object` | [`AdminRegion Schema`](#adminregion-schema) |Administrative region details of the location. +`country`| `object` | [`Code Schema`](#code-schema) |Country associated with the location. +`subDivision`| `object` | [`Code Schema`](#code-schema) |Subdivision associated with the location. +`links`| `list` | [`Link Schema`](#link-schema) |Hateoas links related to the location. -### AdminRegionResponse +### AdminRegion Name| Type | Format |Description ---|----------|-------------------------------|--- `id`| `string` | - |Unique identifier of the admin region. -`names`| `list` | [`Name Schema`](#Name-schema) |Names for the admin region. -`links`| `list` | [`Link Schema`](#Link-schema) |Hateoas Links to related resources. +`names`| `list` | [`Name Schema`](#name-schema) |Names for the admin region. `countryCode`| `string` | - |ISO country code. `subDivCode`| `string` | - |Subdivision (state/province code). +`links`| `list` | [`Link Schema`](#link-schema) |Hateoas Links to related resources. -### CountryListResponse +### CountryListResponse Name| Type | Format |Description ---|--------|-----------------------------------------------------|--- -`countries`| `list` | [`CountryCurrency Schema`](#CountryCurrency-schema) |List of countries with their currency details. +`countries`| `list` | [`CountryCurrency Schema`](#countrycurrency-schema) |List of countries with their currency details. -### CountryCurrency +### CountryCurrency Name| Type | Format |Description ---|-----------|---------------------------------------|--- `code`| `string` | - |ISO country code. -`names`| `list` | [`Name Schema`](#Name-schema) |Names for the countries. -`links`| `list` | [`Link Schema`](#Link-schema) |Hateoas links related to the country. `active`| `boolean` | `true`/`false` |Whether the country is active. -`currencies`| `list` | [`Currency Schema`](#Currency-schema) |List of currencies associated with the country. +`names`| `list` | [`Name Schema`](#name-schema) |Names for the countries. +`currencies`| `list` | [`Currency Schema`](#currency-schema) |List of currencies associated with the country. +`links`| `list` | [`Link Schema`](#link-schema) |Hateoas links related to the country. -### Currency +### Currency Name| Type | Format |Description ---|-----------|------|--- `code`| `string` | - |ISO currency code. -### CountryByCodeResponse +### CountryByCodeResponse Name| Type | Format |Description ---|-----------|------|--- `code`| `string` | - |ISO country code. -`names`| `list` | [`Name Schema`](#Name-schema) |Names for the countries. -`links`| `list` | [`Link Schema`](#Link-schema) |Hateoas links related to the country. `active`| `boolean` | `true`/`false` |Whether the country is active. -`currencies`| `list` | [`Currency Schema`](#Currency-schema) |List of currencies associated with the country. `numCode`| `integer` | - |Numeric ISO code of the country. `alpha3Code`| `string` | - |ISO Alpha-3 code of the country. `distanceUnitCode`| `string` | - |Unit of distance used in the country. +`names`| `list` | [`Name Schema`](#name-schema) |Names for the countries. +`currencies`| `list` | [`Currency Schema`](#currency-schema) |List of currencies associated with the country. +`links`| `list` | [`Link Schema`](#link-schema) |Hateoas links related to the country. -### SubdivisionListResponse +### SubdivisionListResponse Name| Type | Format |Description ---|--------|---------------------------------------------|--- -`subdivisions`| `list` | [`Subdivision Schema`](#Subdivision-schema) |List of subdivisions for a country. +`subdivisions`| `list` | [`Subdivision Schema`](#subdivision-schema) |List of subdivisions for a country. -### Subdivision +### Subdivision Name| Type | Format |Description ---|-----------|------|--- `code`| `string` | - |ISO subdivision code. -`names`| `list` | [`Name Schema`](#Name-schema) |Names for the subdivisions. -`links`| `list` | [`Link Schema`](#Link-schema) |Hateoas links related to the subdivision. `active`| `boolean` | `true`/`false` |Whether the subdivision is active. +`names`| `list` | [`Name Schema`](#name-schema) |Names for the subdivisions. `countryCode`| `string` | - |ISO Alpha-2 code of the country. +`links`| `list` | [`Link Schema`](#link-schema) |Hateoas links related to the subdivision. -### Name +### Name Name| Type | Format |Description ---|----------|------|--- `name`| `string` | - |The actual name value of location/country/subdivision/adminregion. `langCode`| `string` | - |Language code of the name. -### Link +### Link Name| Type | Format |Description ---|----------|------|--- `rel`| `string` | - |Relation type. `href`| `string` | - |Hateoas link. -### Code +### Code Name| Type | Format |Description ---|----------|------|--- `code`| `string` | - |Unique code identifier for countries/subdivisions. -`names`| `list` | [`Name Schema`](#Name-schema) |Names for countries/subdivisions. -`links`| `list` | [`Link Schema`](#Link-schema) |Hateoas links related to countries/subdivisions. +`names`| `list` | [`Name Schema`](#name-schema) |Names for countries/subdivisions. +`links`| `list` | [`Link Schema`](#link-schema) |Hateoas links related to countries/subdivisions. -### Point +### Point Name| Type | Format |Description ---|-----------|------|--- `latitude`| `double` | - |Latitude coordinate. `longitude`| `double` | - |Longitude coordinate. -### LocationName +### LocationName Name| Type | Format |Description ---|-----------|------|--- @@ -626,7 +892,41 @@ Name| Type | Format |Description `name`| `string` | - |Name for the location. `langCode`| `string` | - |Language code. -### Error +### SubdivisionByCodeResponse + +Name| Type | Format |Description +---|-----------|------|--- +`code`| `string` | - |ISO 3166-2 Subdivision code. +`active`| `boolean` | `true`/`false` |Whether the subdivision is active. +`names`| `list` | [`Name Schema`](#name-schema) |Names for the subdivisions. +`countryCode`| `string` | - |ISO Alpha-2 code of the country. +`links`| `list` | [`Link Schema`](#link-schema) |Hateoas links related to the subdivision. + +### AdminRegionList + +Name| Type | Format |Description +---|--------|---------------------------------------------|--- +`adminRegions`| `list` | [`AdminRegionResponse Schema`](#adminregionresponse-schema) |List of AdminRegions for a country code and subdivision codes. + +### AdminRegionResponse + +Name| Type | Format |Description +---|-----------|------|--- +`id`| `string` | - |Unique identifier of the admin region. +`active`| `boolean` | `true`/`false` |Whether the admin region is active. +`names`| `list` | [`Name Schema`](#name-schema) |Names for the admin regions. +`country`| `object` | [`AbstractCode Schema`](#abstractcode-schema) |Country associated with the Adminregion. +`subDivision`| `object` | [`AbstractCode Schema`](#abstractcode-schema) |Subdivision associated with the Adminregion. +`links`| `list` | [`Link Schema`](#link-schema) |Hateoas links related to the admin region. + +### AbstractCode + +Name| Type | Format |Description +---|----------|------|--- +`code`| `string` | - |Unique code identifier for countries/subdivisions. +`links`| `list` | [`Link Schema`](#link-schema) |Hateoas links related to countries/subdivisions. + +### Error Name|Type|Format|Description ---|---|---|---