Localities v5

This API acts as a single source of truth for location-related information, including countries, subdivisions, and specific localities. It enables consistent and reliable data access across multiple business functions and partner systems.

Prior Versions

  • Locations v3 documentation is available here

Limitations

Access to this documentation does not provide access to the API.

Sequence Diagram

A high-level diagram of the Localities Service flow, showing how clients retrieve locality data via endpoints.

Sequence Diagram for Localities

Products and Editions

  • Concur Expense Professional Edition
  • Concur Expense Standard Edition
  • Concur Travel Allowance Professional Edition
  • Concur Travel Allowance Standard Edition
  • Concur Invoice Professional Edition
  • Concur Invoice Standard Edition
  • Concur Request Professional Edition
  • Concur Request Standard Edition

Scope Usage

Name Description Endpoint
locality.read getCountries GET
locality.read getCountryByCode GET
locality.read getLocations GET
locality.read getLocationByLocalityId GET
locality.read getSubdivisions GET

Access Token Usage

This API supports both company level and user level access tokens.

Get Countries

Retrieves a countries list along with currency codes.

Scopes

locality.read - Refer to Scope Usage for full details.

URI

GET https://{region}.api.concursolutions.com/localities/v5/countries

Parameters

None

Payloads

Examples

Request

GET https://us2.api.concursolutions.com/localities/v5/countries
Accept: application/json 
Accept-Language: en 
Authorization: Bearer ${ACCESS_TOKEN}

Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "countries": [
    {
      "code": "AF",
      "active": true,
      "names": [
        {
          "name": "AFGHANISTAN",
          "langCode": "en"
        }
      ],
      "currencies": [
        {
          "code": "AFN"
        }
      ],
      "links": [
        {
          "rel": "self",
          "href": "https://us2.api.concursolutions.com/localities/v5/countries/AF"
        }
      ]
    }
  ]
}

Get Country by Code

Retrieves country details given a country code.

Scopes

locality.read - Refer to Scope Usage for full details.

URI

GET https://{region}.api.concursolutions.com/localities/v5/countries/{countryCode}

Parameters

Name Type Format Description
countryCode string - Required Two-letter ISO countryCode.

Payloads

Examples

Request

GET https://us2.api.concursolutions.com/localities/v5/countries/AF
Accept: application/json 
Accept-Language: en 
Authorization: Bearer ${ACCESS_TOKEN}

Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "code": "AF",
  "active": true,
  "numCode": 826,
  "alpha3Code": "GBR",
  "distanceUnitCode": "MILE",
  "names": [
    {
      "name": "AFGHANISTAN",
      "langCode": "en"
    }
  ],
  "currencies": [
    {
      "code": "AFN"
    }
  ],
  "links": [
    {
      "rel": "self",
      "href": "https://us2.api.concursolutions.com/localities/v5/countries/AF"
    }
  ]
}

Get Locations

Returns details of a locality given a legacy Location Name Key/Locality Code/Location Name Id or matching the given search text for a given company.

Scopes

locality.read - Refer to Scope Usage for full details.

URI

GET https://{region}.api.concursolutions.com/localities/v5/locations?locationNameKey={}&locationNameId={}&locCode={}&searchText={}

Fetches locality data based on query parameters.

Parameters

Only one of these parameters at a time is required: locationNameKey, locationNameId, locCode, or searchText.

Parameter Type Required Condition Description
locationNameKey Integer !Conditional Required if others (locationNameId,locCode or searchText ) not present Unique key for the location name
locationNameId String !Conditional Required if others (locationNameKey,locCode or searchText ) not present UUID identifier of the location name
locCode String !Conditional Required if others (locationNameKey,locationNameId or searchText ) not present Location code
searchText String !Conditional Required if others (locationNameKey,locCode or locationNameId ) not present Free-text for location search
adminRegionId String Optional Only valid with searchText Filter by adminRegionId
countryCode String Optional Only valid with searchText ISO country code
subdivisionCode String Optional Only valid with searchText Subdivision (e.g., state, province) code

Payloads

Examples

Request

GET https://us2.api.concursolutions.com/localities/v5/locations?locCode=DEMUC
Accept: application/json 
Accept-Language: en 
Authorization: Bearer ${ACCESS_TOKEN}

Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "locations": [
    {
      "legacyKey": 5616,
      "code": "DEMUC",
      "id": "0c3f69f8-8867-4fad-9bc9-ade77fc05683",
      "timeZoneOffset": 60,
      "active": true,
      "point": {
        "latitude": 48.15,
        "longitude": 11.583333
      },
      "names": [
        {
          "id": "dff1ef47-b11b-114d-aed4-929e3c5d73d7",
          "name": "Munich",
          "legacyKey": 5705,
          "active": true,
          "langCode": "en"
        }
      ],
      "administrativeRegion": {
        "id": "adminRegionId",
        "names": [
          {
            "name": "BEDFORD COUNTY",
            "langCode": "en"
          }
        ],
        "countryCode": "US",
        "subDivCode": "US-TX",
        "links": [
          {
            "rel": "self",
            "href": "https://us2.api.concursolutions.com/localities/v5/adminRegions/3b353fe3-5e4d-4a7a-8230-8eb44db254d0"
          }
        ]
      },
      "country": {
        "code": "US",
        "names": [
          {
            "name": "USA",
            "langCode": "en"
          }
        ],
        "links": [
          {
            "rel": "self",
            "href": "https://us2.api.concursolutions.com/localities/v5/countries/US"
          }
        ]
      },
      "subDivision": {
        "code": "US-TX",
        "names": [
          {
            "name": "Texas",
            "langCode": "en"
          }
        ],
        "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/locations/0c3f69f8-8867-4fad-9bc9-ade77fc05683"
        }
      ]
    }
  ]
}

Get Location by Locality Id

Returns location details given a Locality Id for a given company.

Scopes

locality.read - Refer to Scope Usage for full details.

URI

GET https://{region}.api.concursolutions.com/localities/v5/locations/{localityId}

Parameters

Name Type Format Description
localityId string - Required Valid UUID of the Locality.

Payloads

Examples

Request

GET https://us2.api.concursolutions.com/localities/v5/locations/0c3f69f8-8867-4fad-9bc9-ade77fc05683
Accept: application/json 
Accept-Language: en 
Authorization: Bearer ${ACCESS_TOKEN}

Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "legacyKey": 5616,
  "code": "DEMUC",
  "id": "0c3f69f8-8867-4fad-9bc9-ade77fc05683",
  "timeZoneOffset": 60,
  "active": true,
  "point": {
    "latitude": 48.15,
    "longitude": 11.583333
  },
  "names": [
    {
      "id": "dff1ef47-b11b-114d-aed4-929e3c5d73d7",
      "name": "Munich",
      "legacyKey": 5705,
      "active": true,
      "langCode": "en"
    }
  ],
  "administrativeRegion": {
    "id": "adminRegionId",
    "names": [
      {
        "name": "BEDFORD COUNTY",
        "langCode": "en"
      }
    ],
    "countryCode": "US",
    "subDivCode": "US-TX",
    "links": [
      {
        "rel": "self",
        "href": "https://us2.api.concursolutions.com/localities/v5/adminRegions/3b353fe3-5e4d-4a7a-8230-8eb44db254d0"
      }
    ]
  },
  "country": {
    "code": "US",
    "names": [
      {
        "name": "USA",
        "langCode": "en"
      }
    ],
    "links": [
      {
        "rel": "self",
        "href": "https://us2.api.concursolutions.com/localities/v5/countries/US"
      }
    ]
  },
  "subDivision": {
    "code": "US-TX",
    "names": [
      {
        "name": "Texas",
        "langCode": "en"
      }
    ],
    "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/locations/0c3f69f8-8867-4fad-9bc9-ade77fc05683"
    }
  ]
}

Get Subdivisions

Retrieves list of subdivisions given country code.

Scopes

locality.read - Refer to Scope Usage for full details.

URI

GET https://{region}.api.concursolutions.com/localities/v5/subdivisions?countryCode={countryCode}

Parameters

Name Type Format Description
countryCode string - Required Two letter ISO countryCode.

Payloads

Examples

Request

GET https://us2.api.concursolutions.com/localities/v5/subdivisions?countryCode=AU
Accept: application/json 
Accept-Language: en 
Authorization: Bearer ${ACCESS_TOKEN}

Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "subdivisions": [
    {
      "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"
        }
      ]
    }
  ]
}

Schemas

LocationListResponse

Name Type Format Description
Locations List LocationDetailsResponse Schema All active locations for the given company Id.

LocationDetailsResponse

Name Type Format Description
legacyKey integer - Numeric Identifier for the location.
code string - Location code.
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 Geographical coordinates of the location.
names list LocationName Schema Names for the location.
administrativeRegion object AdministrativeRegionResponse Schema Administrative region details of the location.
country object Code Schema Country associated with the location.
subDivision object Code Schema Subdivision associated with the location.
links list Link Schema Hateoas links related to the location.

AdminRegionResponse

Name Type Format Description
id string - Unique identifier of the admin region.
names list Name Schema Names for the admin region.
links list Link Schema Hateoas Links to related resources.
countryCode string - ISO country code.
subDivCode string - Subdivision (state/province code).

CountryListResponse

Name Type Format Description
countries list CountryCurrency Schema List of countries with their currency details.

CountryCurrency

Name Type Format Description
code string - ISO country code.
names list Name Schema Names for the countries.
links list Link Schema Hateoas links related to the country.
active boolean true/false Whether the country is active.
currencies list Currency Schema List of currencies associated with the country.

Currency

Name Type Format Description
code string - ISO currency code.

CountryByCodeResponse

Name Type Format Description
code string - ISO country code.
names list Name Schema Names for the countries.
links list Link Schema Hateoas links related to the country.
active boolean true/false Whether the country is active.
currencies list 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.

SubdivisionListResponse

Name Type Format Description
subdivisions list Subdivision Schema List of subdivisions for a country.

Subdivision

Name Type Format Description
code string - ISO subdivision code.
names list Name Schema Names for the subdivisions.
links list Link Schema Hateoas links related to the subdivision.
active boolean true/false Whether the subdivision is active.
countryCode string - ISO Alpha-2 code of the country.

Name

Name Type Format Description
name string - The actual name value of location/country/subdivision/adminregion.
langCode string - Language code of the name.
Name Type Format Description
rel string - Relation type.
href string - Hateoas link.

Code

Name Type Format Description
code string - Unique code identifier for countries/subdivisions.
names list Name Schema Names for countries/subdivisions.
links list Link Schema Hateoas links related to countries/subdivisions.

Point

Name Type Format Description
latitude double - Latitude coordinate.
longitude double - Longitude coordinate.

LocationName

Name Type Format Description
id string - Unique identifier for the location name.
legacyKey integer - Numeric identifier for the location.
active boolean true/false Whether the location is active.
name string - Name for the location.
langCode string - Language code.

Error

Name Type Format Description
timestamp string date-time Required The time when the error was captured.
status string - Required The HTTP response code and phrase for the response.
errorMessage string - Required The detailed error message.
path string - Required The URI of the attempted request.

On this page