> This page is for Developer. > For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.bigcommerce.com/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.bigcommerce.com/_mcp/server. # Get State GET https://api-b2b.bigcommerce.com/api/v3/io/states Retrieves state or province information based on the state name or two-letter code entered in the parameters. The response can be used to provide a valid state name or code in Company addresses. Use the `country` parameter to specify the country associated with the queried state. If left blank, the endpoint uses the United States by default. Note that only the countries listed below will return state or province values. When [creating](#create-a-company-address) or [updating](#update-an-address) addresses in these countries, you must include state information. * Argentina * Australia * Austria * Brazil * Canada * Chile * Germany * India * Indonesia * Ireland * Italy * Japan * Malaysia * Mexico * Myanmar * New Zealand * Philippines * Qatar * Romania * South Africa * Spain * Switzerland * United Arab Emirates * United States (default) Use the `searchType` parameter to specify whether you are searching by a state's name or its two-letter [ISO code](https://www.iso.org/obp/ui/#search), and then add the appropriate value for the state to the `q` parameter. Reference: https://docs.bigcommerce.com/developer/api-reference/rest/b2b/management/addresses/get-addresses-states-state-name-code ## Authentication - `X-Auth-Token` header (required) — | Header | Argument | Description | |:-------|:---------|:------------| | `X-Auth-Token` | `access_token` | For more about API accounts that generate `access_token`s, see our [Guide to API Accounts](/developer/docs/overview/api-fundamentals/api-accounts). | For example requests and more information about authenticating BigCommerce APIs, see [Authentication and Example Requests](/developer/docs/overview/api-fundamentals/api-accounts#x-auth-token-header-example-requests). For more about BigCommerce OAuth scopes, see our [Guide to API Accounts](/developer/docs/overview/api-fundamentals/api-accounts#oauth-scopes). For a list of API status codes, see [API Status Codes](/developer/api-reference/rest/overview#rest-http-status-codes). - `X-Store-Hash` header (required) — | Header | Argument | Description | |:-------|:---------|:------------| | `X-Store-Hash` | `store_hash` | The unique store hash associated with a BigCommerce store that has B2B Edition enabled. | ## Request ### Query parameters - `searchType` (enum, required) — Determines whether you are searching by a state or province's name (`0`) or its two-letter ISO code (`1`). This parameter also defines the value type for the `country` parameter. - Allowed values: `0`, `1` - `q` (string, required) — The state's name or its two-letter ISO code, depending on the specified `searchType`. **Note:** The state information entered for the parameter must correspond to the country specified in the `country` value. - `country` (string, optional, default: US / United States) — The country's name or its two-letter ISO code, depending on the specified `searchType`. ## Response ### 200 OK - `code` (double, required, default: 200) - `data` (StatesGetResponsesContentApplicationJsonSchemaData, required) - `meta` (StatesGetResponsesContentApplicationJsonSchemaMeta, required) ## Errors ### 404 Not Found Error Not Found This error occurs if the state name or code does not match the country specified in the country parameter. When querying states/provinces outside of the United States, you must use the `country` parameter, and its value must be formatted in accordance with the `searchBy` parameter. - `code` (double, required) - `data` (StatesGetResponsesContentApplicationJsonSchemaData, required) - `meta` (StatesGetResponsesContentApplicationJsonSchemaMeta, required) ## Types ### StatesGetResponsesContentApplicationJsonSchemaData ### StatesGetResponsesContentApplicationJsonSchemaMeta - `message` (string, required) ## Examples **Response** ```json { "code": 200, "data": { "stateCode": "TX", "stateName": "Texas" }, "meta": { "message": "SUCCESS" } } ``` **SDK Code** ```python import requests url = "https://api-b2b.bigcommerce.com/api/v3/io/states" querystring = {"country":"US(the searchType should be 1), United States(the searchType should be 0)","q":"TX (the searchType should be 1); Texas (the searchType should be 0)","searchType":"0"} headers = {"X-Auth-Token": ""} response = requests.get(url, headers=headers, params=querystring) print(response.json()) ``` ```javascript const url = 'https://api-b2b.bigcommerce.com/api/v3/io/states?country=US%28the++searchType+should+be+1%29%2C+United+States%28the+searchType+should+be+0%29&q=TX+%28the+searchType+should+be+1%29%3B++Texas+%28the+searchType+should+be+0%29&searchType=0'; const options = {method: 'GET', headers: {'X-Auth-Token': ''}}; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go package main import ( "fmt" "net/http" "io" ) func main() { url := "https://api-b2b.bigcommerce.com/api/v3/io/states?country=US%28the++searchType+should+be+1%29%2C+United+States%28the+searchType+should+be+0%29&q=TX+%28the+searchType+should+be+1%29%3B++Texas+%28the+searchType+should+be+0%29&searchType=0" req, _ := http.NewRequest("GET", url, nil) req.Header.Add("X-Auth-Token", "") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby require 'uri' require 'net/http' url = URI("https://api-b2b.bigcommerce.com/api/v3/io/states?country=US%28the++searchType+should+be+1%29%2C+United+States%28the+searchType+should+be+0%29&q=TX+%28the+searchType+should+be+1%29%3B++Texas+%28the+searchType+should+be+0%29&searchType=0") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Get.new(url) request["X-Auth-Token"] = '' response = http.request(request) puts response.read_body ``` ```java import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.get("https://api-b2b.bigcommerce.com/api/v3/io/states?country=US%28the++searchType+should+be+1%29%2C+United+States%28the+searchType+should+be+0%29&q=TX+%28the+searchType+should+be+1%29%3B++Texas+%28the+searchType+should+be+0%29&searchType=0") .header("X-Auth-Token", "") .asString(); ``` ```php request('GET', 'https://api-b2b.bigcommerce.com/api/v3/io/states?country=US%28the++searchType+should+be+1%29%2C+United+States%28the+searchType+should+be+0%29&q=TX+%28the+searchType+should+be+1%29%3B++Texas+%28the+searchType+should+be+0%29&searchType=0', [ 'headers' => [ 'X-Auth-Token' => '', ], ]); echo $response->getBody(); ``` ```csharp using RestSharp; var client = new RestClient("https://api-b2b.bigcommerce.com/api/v3/io/states?country=US%28the++searchType+should+be+1%29%2C+United+States%28the+searchType+should+be+0%29&q=TX+%28the+searchType+should+be+1%29%3B++Texas+%28the+searchType+should+be+0%29&searchType=0"); var request = new RestRequest(Method.GET); request.AddHeader("X-Auth-Token", ""); IRestResponse response = client.Execute(request); ``` ```swift import Foundation let headers = ["X-Auth-Token": ""] let request = NSMutableURLRequest(url: NSURL(string: "https://api-b2b.bigcommerce.com/api/v3/io/states?country=US%28the++searchType+should+be+1%29%2C+United+States%28the+searchType+should+be+0%29&q=TX+%28the+searchType+should+be+1%29%3B++Texas+%28the+searchType+should+be+0%29&searchType=0")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "GET" request.allHTTPHeaderFields = headers let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ```