BigCommerce Geography is a division within BigCommerce that focuses on optimizing the geographic reach and impact of online businesses. This team analyzes market trends, consumer behavior, and regional preferences to help businesses expand their reach and grow their customer base in different geographical locations.
openapi: 3.0.0
info:
version: 1.0.0-oas3
title: BigCommerce Geography
description: Get countries, states, and provinces.
paths:
/countries:
get:
description: >-
Get a list of all countries available. A country or territory,
identifiable by an ISO 3166 country code.
summary: BigCommerce Get All Countries
operationId: getCountries
parameters:
- name: Accept
in: header
required: true
description: ''
schema:
type: string
default: application/json
- name: Content-Type
in: header
required: true
description: ''
schema:
type: string
default: application/json
- name: page
in: query
required: false
description: Number of pages
schema:
type: number
exclusiveMinimum: false
exclusiveMaximum: false
- name: limit
in: query
required: false
description: Count per page
schema:
type: number
exclusiveMinimum: false
exclusiveMaximum: false
- in: query
name: country
schema:
type: string
- in: query
name: country_iso2
schema:
type: string
- in: query
name: country_iso3
schema:
type: string
responses:
'200':
$ref: '#/components/responses/countryCollection_Resp'
tags:
- Countries
/countries/{id}:
get:
description: >-
Returns a single *Country*. Gets a country. A country or territory,
identifiable by an ISO 3166 country code.
summary: BigCommerce Get a Country
operationId: getCountry
parameters:
- name: id
in: path
required: true
description: The ID of the country.
schema:
type: integer
exclusiveMinimum: false
exclusiveMaximum: false
- name: Accept
in: header
required: true
description: ''
schema:
type: string
default: application/json
- name: Content-Type
in: header
required: true
description: ''
schema:
type: string
default: application/json
responses:
'200':
$ref: '#/components/responses/countriesResponse'
tags:
- Countries
parameters:
- name: id
in: path
required: true
schema:
type: string
/countries/{country_id}/states:
get:
description: |-
Returns a list of *States* belonging to a *Country*.
A state or province, identifiable by an ISO 3166 subdivision code.
summary: BigCommerce Get All Countryʼs States
operationId: getCountryStates
parameters:
- name: country_id
in: path
required: true
description: Id of the country
schema:
type: integer
exclusiveMinimum: false
exclusiveMaximum: false
- name: Accept
in: header
required: true
description: ''
schema:
type: string
- name: Content-Type
in: header
required: true
description: ''
schema:
type: string
- name: state
in: query
required: false
description: Name of the state/province.
schema:
type: string
- name: state_abbreviation
in: query
required: false
description: Abbreviation for the state/province.
schema:
type: string
- name: page
in: query
required: false
description: Number of pages
schema:
type: number
exclusiveMinimum: false
exclusiveMaximum: false
- name: limit
in: query
required: false
description: Count per page
schema:
type: number
exclusiveMinimum: false
exclusiveMaximum: false
responses:
'200':
$ref: '#/components/responses/countriesStatesCollectionResponse'
tags:
- States
parameters:
- name: country_id
in: path
required: true
schema:
type: string
/countries/{country_id}/states/{id}:
get:
operationId: getCountryState
description: |-
Returns a *State*.
A state or province, identifiable by an ISO 3166 subdivision code.
summary: BigCommerce Get a Countryʼs State
parameters:
- name: country_id
in: path
required: true
description: Id of the country
schema:
type: integer
exclusiveMinimum: false
exclusiveMaximum: false
- name: id
in: path
required: true
description: Id of the states
schema:
type: integer
exclusiveMinimum: false
exclusiveMaximum: false
- name: Accept
in: header
required: true
description: ''
schema:
type: string
default: application/json
- name: Content-Type
in: header
required: true
description: ''
schema:
type: string
default: application/json
responses:
'200':
$ref: '#/components/responses/countriesStatesResponse'
x-unitTests: []
x-operation-settings:
CollectParameters: false
AllowDynamicQueryParameters: false
AllowDynamicFormParameters: false
IsMultiContentStreaming: false
tags:
- States
parameters:
- name: country_id
in: path
required: true
schema:
type: string
- schema:
type: string
name: id
in: path
required: true
/countries/count:
get:
responses:
'200':
$ref: '#/components/responses/countResponse'
summary: BigCommerce Get a Count of All Countries
tags:
- Countries
operationId: getCountriesCount
description: Returns a count of all countries.
/countries/states/count:
get:
operationId: getStatesCount
responses:
'200':
$ref: '#/components/responses/countResponse'
summary: BigCommerce Get a Count of All States
tags:
- States
description: Returns a count of all states.
/countries/states:
get:
responses:
'200':
$ref: '#/components/responses/countriesStatesCollectionResponse'
summary: BigCommerce Get All States
tags:
- States
description: Returns a list of all states.
operationId: getStates
parameters:
- schema:
type: integer
in: query
name: limit
description: The number of results to return per request.
- schema:
type: integer
in: query
name: page
description: The ordered grouping of results to return.
/countries/{country_id}/states/count:
get:
operationId: getCountryStatesCount
responses:
'200':
$ref: '#/components/responses/countResponse'
summary: BigCommerce Get a Count of Country’s States
tags:
- States
description: Returns a count of a countryʼs states.
parameters:
- name: country_id
in: path
required: true
schema:
type: string
security:
- X-Auth-Token: []
tags:
- name: Countries
- name: States
servers:
- url: https://api.bigcommerce.com/stores/{store_hash}/v2
variables:
store_hash:
default: store_hash
description: Permanent ID of the BigCommerce store.
description: BigCommerce API Gateway
components:
responses:
countriesResponse:
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/country_Full'
examples:
response:
value:
id: 1
country: Afghanistan
country_iso2: AF
country_iso3: AFG
states:
url: >-
https://api.bigcommerce.com/stores/h10wocxy6s/v2/countries/1/states
resource: /countries/1/states
countriesStatesResponse:
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/countriesState_Full'
countryCollection_Resp:
description: ''
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/country_Full'
example:
- id: 1
country: Afghanistan
country_iso2: AF
country_iso3: AFG
states:
url: >-
https://api.bigcommerce.com/stores/store_hash/v2/countries/1/states
resource: /countries/1/states
- id: 2
country: Albania
country_iso2: AL
country_iso3: ALB
states:
url: >-
https://api.bigcommerce.com/stores/store_hash/v2/countries/2/states
resource: /countries/2/states
countriesStatesCollectionResponse:
description: ''
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/countriesState_Full'
countResponse:
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/count_Full'
examples:
response:
value:
count: 241
securitySchemes:
X-Auth-Token:
name: X-Auth-Token
description: >-
### OAuth scopes
| UI Name | Permission | Parameter |
|:--|:--|:-|
| Information & Settings | modify | `store_v2_information` |
| Information & Settings | read-only | `store_v2_information_read_only`
|
### Authentication header
| Header | Argument | Description |
|:-|:|:|
| `X-Auth-Token` | `access_token` | For more about API accounts that
generate `access_token`s, see our [Guide to API
Accounts](/docs/start/authentication/api-accounts). |
### Further reading
For example requests and more information about authenticating
BigCommerce APIs, see [Authentication and Example
Requests](/docs/start/authentication#x-auth-token-header-example-requests).
For more about BigCommerce OAuth scopes, see our [Guide to API
Accounts](/docs/start/authentication/api-accounts#oauth-scopes).
For a list of API status codes, see [API Status
Codes](/docs/start/about/status-codes).
type: apiKey
in: header
schemas:
country_Full:
title: country_Full
example:
id: 13
country: Australia
country_iso2: AU
country_iso3: AUS
states:
url: >-
https://api.bigcommerce.com/stores/{store_hash}/v2/countries/13/states
resource: /countries/13/states
allOf:
- type: object
properties:
id:
type: integer
description: Id of the country.
example: 13
- $ref: '#/components/schemas/country_Base'
- type: object
properties:
states:
$ref: '#/components/schemas/countriesStates_Full'
x-internal: false
countriesStates_Full:
title: countriesStates_Full
type: object
properties:
url:
description: ''
example: >-
https://api.bigcommerce.com/stores/{store_hash}/v2/countries/13/states
type: string
resource:
description: ''
example: /countries/13/states
type: string
description: Refers to the `states` object return in `GET` countries requests.
x-internal: false
countriesState_Full:
title: countriesState_Full
example:
id: 208
state: Australian Capital Territory
state_abbreviation: ACT
country_id: 13
type: object
properties:
id:
description: Numeric ID of the state/province.
example: 208
type: integer
state:
description: Name of the state/province.
example: Australian Capital Territory
type: string
state_abbreviation:
description: Abbreviation for the state/province.
example: ACT
type: string
country_id:
description: Numeric ID of the state’s/province’s associated country.
example: 13
type: integer
description: 'Refers to the state returned in `GET` states requests. '
x-internal: false
country_Base:
type: object
title: country_Base
properties:
country:
type: string
example: Australia
description: Country name.
country_iso2:
type: string
description: 2-letter country code.
example: AU
country_iso3:
type: string
description: 3-letter country code.
example: AUS
x-internal: false
count_Full:
type: object
properties:
count:
type: integer
minimum: 1
x-internal: false