States list

Retrieves a paginated list of states/regions with their geographic identifiers.

This endpoint provides standardized state information for use in address forms, geographic filtering, and regional data management.

Endpoint

GET/v2/geo/state

Link

Gateway APIstagep.tst-apidmndelss.com

Request

Headers

Key	Value	Required
Authorization	123	Yes
Accept	application/json	Yes

Query Parameters

Parameter	Type	Description	Required	Example
filter	string	Optional filter for state names or codes.	No	"california"
meta.page	integer	Page number (starts from 0).	No	0
meta.pageSize	integer	Items count per page.	No	50

---

Response (200 OK)

Returns a paginated list of state/region objects with geographic identifiers and pagination metadata.

Response Fields

Items Array

Array of state objects with the following structure:

Field	Type	Description	Example
id	integer	Unique state ID.	5
iso	string	ISO country code the state belongs to.	"US"
code	string	State/region code (abbreviation).	"CA"
name	string	Full state/region name.	"California"

Meta Object

Pagination metadata for the response:

Field	Type	Description	Example
pageSize	integer	Number of items per page.	50
page	integer	Current page number (0-based).	0
total	string	Total number of items across all pages.	"50"

---

Examples

Request (All States with Pagination)

bash

curl -X GET 'https://stagep.tst-apidmndelss.com/v2/geo/state?meta.page=0&meta.pageSize=10' \
  -H 'Authorization: 123' \
  -H 'Accept: application/json'

Response

json

{
  "items": [
    {
      "id": 1,
      "iso": "US",
      "code": "AL",
      "name": "Alabama"
    },
    {
      "id": 2,
      "iso": "US",
      "code": "AK",
      "name": "Alaska"
    },
    {
      "id": 3,
      "iso": "US",
      "code": "AZ",
      "name": "Arizona"
    },
    {
      "id": 4,
      "iso": "US",
      "code": "AR",
      "name": "Arkansas"
    },
    {
      "id": 5,
      "iso": "US",
      "code": "CA",
      "name": "California"
    },
    {
      "id": 6,
      "iso": "US",
      "code": "CO",
      "name": "Colorado"
    },
    {
      "id": 7,
      "iso": "US",
      "code": "CT",
      "name": "Connecticut"
    },
    {
      "id": 8,
      "iso": "US",
      "code": "DE",
      "name": "Delaware"
    },
    {
      "id": 9,
      "iso": "US",
      "code": "FL",
      "name": "Florida"
    },
    {
      "id": 10,
      "iso": "US",
      "code": "GA",
      "name": "Georgia"
    }
  ],
  "meta": {
    "pageSize": 10,
    "page": 0,
    "total": "50"
  }
}

Request (Filtered by Name)

bash

curl -X GET 'https://stagep.tst-apidmndelss.com/v2/geo/state?filter=new&meta.page=0&meta.pageSize=5' \
  -H 'Authorization: 123' \
  -H 'Accept: application/json'

Response (Filtered)

json

{
  "items": [
    {
      "id": 31,
      "iso": "US",
      "code": "NH",
      "name": "New Hampshire"
    },
    {
      "id": 32,
      "iso": "US",
      "code": "NJ",
      "name": "New Jersey"
    },
    {
      "id": 33,
      "iso": "US",
      "code": "NM",
      "name": "New Mexico"
    },
    {
      "id": 34,
      "iso": "US",
      "code": "NY",
      "name": "New York"
    },
    {
      "id": 46,
      "iso": "GB",
      "code": "NIR",
      "name": "Northern Ireland"
    }
  ],
  "meta": {
    "pageSize": 5,
    "page": 0,
    "total": "5"
  }
}

Request (Filtered by Code)

bash

curl -X GET 'https://stagep.tst-apidmndelss.com/v2/geo/state?filter=ca&meta.page=0&meta.pageSize=10' \
  -H 'Authorization: 123' \
  -H 'Accept: application/json'

Response (Code Filter)

json

{
  "items": [
    {
      "id": 5,
      "iso": "US",
      "code": "CA",
      "name": "California"
    },
    {
      "id": 51,
      "iso": "CA",
      "code": "AB",
      "name": "Alberta"
    },
    {
      "id": 52,
      "iso": "CA",
      "code": "BC",
      "name": "British Columbia"
    },
    {
      "id": 53,
      "iso": "CA",
      "code": "MB",
      "name": "Manitoba"
    }
  ],
  "meta": {
    "pageSize": 10,
    "page": 0,
    "total": "4"
  }
}

Request (Default Pagination)

bash

curl -X GET 'https://stagep.tst-apidmndelss.com/v2/geo/state' \
  -H 'Authorization: 123' \
  -H 'Accept: application/json'

Response (Default)

json

{
  "items": [
    {
      "id": 1,
      "iso": "US",
      "code": "AL",
      "name": "Alabama"
    },
    {
      "id": 2,
      "iso": "US",
      "code": "AK",
      "name": "Alaska"
    },
    {
      "id": 3,
      "iso": "US",
      "code": "AZ",
      "name": "Arizona"
    },
    {
      "id": 4,
      "iso": "US",
      "code": "AR",
      "name": "Arkansas"
    },
    {
      "id": 5,
      "iso": "US",
      "code": "CA",
      "name": "California"
    }
  ],
  "meta": {
    "pageSize": 50,
    "page": 0,
    "total": "50"
  }
}

---

Error Responses

1. Invalid Page Parameters:

   json

   { "error": "Invalid page parameters: page must be >= 0" }

2. Unauthorized:

   json

   { "error": "Unauthorized" }

3. Rate Limit Exceeded:

   json

   { "error": "Rate limit exceeded" }

---

Notes

• Pagination: Default page size is typically 50 items if not specified
• Filtering: The filter parameter searches both state names and codes
• International Support: Includes states/regions from multiple countries (US, CA, GB, etc.)
• ISO Codes: Uses standard ISO 3166 country codes
• Sorting: Results are typically sorted by country ISO code and state name
• Performance: Efficient for dropdown population and geographic data management

Common Use Cases:

• Address form state/region dropdowns
• Geographic filtering and reporting
• Regional data analysis
• Compliance with geographic requirements
• Multi-country application support

Filter Behavior:

• Case-insensitive search
• Matches partial names and codes
• Searches across all countries
• Returns results from any matching field (name or code)

Real request example

Authorization:
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOjE2NCwiZXhwIjoxNzYxMTM1OTI3LCJrZXkiOiI1Y2ZiOGZjN2RmYjk4ZjVkYmIyZTgwNTVkZWFhN2U2Zjk4MzEyYmE3Iiwib3RwX3ZlcmlmaWVkIjpmYWxzZX0.bvY7rDxLEZGnuZ8WcyMlqB-VQKeKCRCVTM5UZYPRQzg

Real response example

200 OK

{
  "items": [
    {
      "id": 1,
      "iso": "AZ",
      "code": "KALBAJAR",
      "name": "Kalbajar"
    },
    {
      "id": 2,
      "iso": "AZ",
      "code": "SHUSHA",
      "name": "Shusha"
    },
    {
      "id": 3,
      "iso": "AZ",
      "code": "TARTAR",
      "name": "Tartar"
    },
    {
      "id": 4,
      "iso": "AZ",
      "code": "KHOJALY",
      "name": "Khojaly"
    },
    {
      "id": 5,
      "iso": "AZ",
      "code": "KHOJAVEND",
      "name": "Khojavend"
    },
    {
      "id": 6,
      "iso": "AZ",
      "code": "ABSHERON",
      "name": "Absheron"
    },
    {
      "id": 7,
      "iso": "AZ",
      "code": "AGHJABADI",
      "name": "Aghjabadi"
    },
    {
      "id": 8,
      "iso": "AZ",
      "code": "AGHDAM",
      "name": "Aghdam"
    },
    {
      "id": 9,
      "iso": "AZ",
      "code": "AGDASH",
      "name": "Agdash"
    },
    {
      "id": 10,
      "iso": "AZ",
      "code": "AGHSTAFA",
      "name": "Aghstafa"
    },
    {
      "id": 11,
      "iso": "AZ",
      "code": "AGSU",
      "name": "Agsu"
    },
    {
      "id": 12,
      "iso": "AZ",
      "code": "SIRVAN",
      "name": "Sirvan"
    },
    {
      "id": 13,
      "iso": "AZ",
      "code": "ASTARA",
      "name": "Astara"
    },
    {
      "id": 14,
      "iso": "AZ",
      "code": "BAKU",
      "name": "Baku"
    },
    {
      "id": 15,
      "iso": "AZ",
      "code": "BALAKAN",
      "name": "Balakan"
    },
    {
      "id": 16,
      "iso": "AZ",
      "code": "BARDA",
      "name": "Barda"
    },
    {
      "id": 17,
      "iso": "AZ",
      "code": "BEYLAGAN",
      "name": "Beylagan"
    },
    {
      "id": 18,
      "iso": "AZ",
      "code": "BILASUVAR",
      "name": "Bilasuvar"
    },
    {
      "id": 19,
      "iso": "AZ",
      "code": "JABRAYIL",
      "name": "Jabrayil"
    },
    {
      "id": 20,
      "iso": "AZ",
      "code": "JALILABAD",
      "name": "Jalilabad"
    },
    {
      "id": 21,
      "iso": "AZ",
      "code": "DASHKASAN",
      "name": "Dashkasan"
    },
    {
      "id": 22,
      "iso": "AZ",
      "code": "SHABRAN",
      "name": "Shabran"
    },
    {
      "id": 23,
      "iso": "AZ",
      "code": "FUZULI",
      "name": "Fuzuli"
    },
    {
      "id": 24,
      "iso": "AZ",
      "code": "GADABAY",
      "name": "Gadabay"
    },
    {
      "id": 25,
      "iso": "AZ",
      "code": "GANJA",
      "name": "Ganja"
    },
    {
      "id": 26,
      "iso": "AZ",
      "code": "GORANBOY",
      "name": "Goranboy"
    },
    {
      "id": 27,
      "iso": "AZ",
      "code": "GOYCHAY",
      "name": "Goychay"
    },
    {
      "id": 28,
      "iso": "AZ",
      "code": "HAJIGABUL",
      "name": "Hajigabul"
    },
    {
      "id": 29,
      "iso": "AZ",
      "code": "IMISHLI",
      "name": "Imishli"
    },
    {
      "id": 30,
      "iso": "AZ",
      "code": "ISMAYILLI",
      "name": "Ismayilli"
    },
    {
      "id": 31,
      "iso": "AZ",
      "code": "KURDAMIR",
      "name": "Kurdamir"
    },
    {
      "id": 32,
      "iso": "AZ",
      "code": "LACHIN",
      "name": "Lachin"
    },
    {
      "id": 33,
      "iso": "AZ",
      "code": "LANKARAN",
      "name": "Lankaran"
    },
    {
      "id": 34,
      "iso": "AZ",
      "code": "LERIK",
      "name": "Lerik"
    },
    {
      "id": 35,
      "iso": "AZ",
      "code": "MASALLY",
      "name": "Masally"
    },
    {
      "id": 36,
      "iso": "AZ",
      "code": "MINGACHEVIR",
      "name": "Mingachevir"
    },
    {
      "id": 37,
      "iso": "AZ",
      "code": "NAFTALAN",
      "name": "Naftalan"
    },
    {
      "id": 38,
      "iso": "AZ",
      "code": "NEFTCHALA",
      "name": "Neftchala"
    },
    {
      "id": 39,
      "iso": "AZ",
      "code": "OGHUZ",
      "name": "Oghuz"
    },
    {
      "id": 40,
      "iso": "AZ",
      "code": "QABALA",
      "name": "Qabala"
    },
    {
      "id": 41,
      "iso": "AZ",
      "code": "QAKH",
      "name": "Qakh"
    },
    {
      "id": 42,
      "iso": "AZ",
      "code": "QAZAX",
      "name": "Qazax"
    },
    {
      "id": 43,
      "iso": "AZ",
      "code": "GOBUSTAN",
      "name": "Gobustan"
    },
    {
      "id": 44,
      "iso": "AZ",
      "code": "QUBA",
      "name": "Quba"
    },
    {
      "id": 45,
      "iso": "AZ",
      "code": "QUBADLI",
      "name": "Qubadli"
    },
    {
      "id": 46,
      "iso": "AZ",
      "code": "QUSAR",
      "name": "Qusar"
    },
    {
      "id": 47,
      "iso": "AZ",
      "code": "SAATLY",
      "name": "Saatly"
    },
    {
      "id": 48,
      "iso": "AZ",
      "code": "SABIRABAD",
      "name": "Sabirabad"
    },
    {
      "id": 49,
      "iso": "AZ",
      "code": "SHAKI",
      "name": "Shaki"
    },
    {
      "id": 50,
      "iso": "AZ",
      "code": "SALYAN",
      "name": "Salyan"
    },
    {
      "id": 51,
      "iso": "AZ",
      "code": "SHAMAKHI",
      "name": "Shamakhi"
    },
    {
      "id": 52,
      "iso": "AZ",
      "code": "SHAMKIR",
      "name": "Shamkir"
    },
    {
      "id": 53,
      "iso": "AZ",
      "code": "SAMUKH",
      "name": "Samukh"
    },
    {
      "id": 54,
      "iso": "AZ",
      "code": "SIYAZAN",
      "name": "Siyazan"
    },
    {
      "id": 55,
      "iso": "AZ",
      "code": "SUMGAIT",
      "name": "Sumgait"
    },
    {
      "id": 56,
      "iso": "AZ",
      "code": "TOVUZ",
      "name": "Tovuz"
    },
    {
      "id": 57,
      "iso": "AZ",
      "code": "UJAR",
      "name": "Ujar"
    },
    {
      "id": 58,
      "iso": "AZ",
      "code": "KHACHMAZ",
      "name": "Khachmaz"
    },
    {
      "id": 59,
      "iso": "AZ",
      "code": "KHANKENDI",
      "name": "Khankendi"
    },
    {
      "id": 60,
      "iso": "AZ",
      "code": "GOYGOL",
      "name": "Goygol"
    },
    {
      "id": 61,
      "iso": "AZ",
      "code": "KHIZI",
      "name": "Khizi"
    },
    {
      "id": 62,
      "iso": "AZ",
      "code": "YARDIMLI",
      "name": "Yardimli"
    },
    {
      "id": 63,
      "iso": "AZ",
      "code": "YEVLAKH",
      "name": "Yevlakh"
    },
    {
      "id": 64,
      "iso": "AZ",
      "code": "ZANGILAN",
      "name": "Zangilan"
    },
    {
      "id": 65,
      "iso": "AZ",
      "code": "ZAGATALA",
      "name": "Zagatala"
    },
    {
      "id": 66,
      "iso": "AZ",
      "code": "ZARDAB",
      "name": "Zardab"
    },
    {
      "id": 67,
      "iso": "US",
      "code": "AL",
      "name": "Alabama"
    },
    {
      "id": 68,
      "iso": "US",
      "code": "AK",
      "name": "Alaska"
    },
    {
      "id": 69,
      "iso": "US",
      "code": "AZ",
      "name": "Arizona"
    },
    {
      "id": 70,
      "iso": "US",
      "code": "AR",
      "name": "Arkansas"
    },
    {
      "id": 71,
      "iso": "US",
      "code": "CA",
      "name": "California"
    },
    {
      "id": 72,
      "iso": "US",
      "code": "CO",
      "name": "Colorado"
    },
    {
      "id": 73,
      "iso": "US",
      "code": "CT",
      "name": "Connecticut"
    },
    {
      "id": 74,
      "iso": "US",
      "code": "DE",
      "name": "Delaware"
    },
    {
      "id": 75,
      "iso": "US",
      "code": "FL",
      "name": "Florida"
    },
    {
      "id": 76,
      "iso": "US",
      "code": "GA",
      "name": "Georgia"
    },
    {
      "id": 77,
      "iso": "US",
      "code": "HI",
      "name": "Hawaii"
    },
    {
      "id": 78,
      "iso": "US",
      "code": "ID",
      "name": "Idaho"
    },
    {
      "id": 79,
      "iso": "US",
      "code": "IL",
      "name": "Illinois"
    },
    {
      "id": 80,
      "iso": "US",
      "code": "IN",
      "name": "Indiana"
    },
    {
      "id": 81,
      "iso": "US",
      "code": "IA",
      "name": "Iowa"
    },
    {
      "id": 82,
      "iso": "US",
      "code": "KS",
      "name": "Kansas"
    },
    {
      "id": 83,
      "iso": "US",
      "code": "KY",
      "name": "Kentucky"
    },
    {
      "id": 84,
      "iso": "US",
      "code": "LA",
      "name": "Louisiana"
    },
    {
      "id": 85,
      "iso": "US",
      "code": "ME",
      "name": "Maine"
    },
    {
      "id": 86,
      "iso": "US",
      "code": "MD",
      "name": "Maryland"
    },
    {
      "id": 87,
      "iso": "US",
      "code": "MA",
      "name": "Massachusetts"
    },
    {
      "id": 88,
      "iso": "US",
      "code": "MI",
      "name": "Michigan"
    },
    {
      "id": 89,
      "iso": "US",
      "code": "MN",
      "name": "Minnesota"
    },
    {
      "id": 90,
      "iso": "US",
      "code": "MS",
      "name": "Mississippi"
    },
    {
      "id": 91,
      "iso": "US",
      "code": "MO",
      "name": "Missouri"
    },
    {
      "id": 92,
      "iso": "US",
      "code": "MT",
      "name": "Montana"
    },
    {
      "id": 93,
      "iso": "US",
      "code": "NE",
      "name": "Nebraska"
    },
    {
      "id": 94,
      "iso": "US",
      "code": "NV",
      "name": "Nevada"
    },
    {
      "id": 95,
      "iso": "US",
      "code": "NH",
      "name": "New Hampshire"
    },
    {
      "id": 96,
      "iso": "US",
      "code": "NJ",
      "name": "New Jersey"
    },
    {
      "id": 97,
      "iso": "US",
      "code": "NM",
      "name": "New Mexico"
    },
    {
      "id": 98,
      "iso": "US",
      "code": "NY",
      "name": "New York"
    },
    {
      "id": 99,
      "iso": "US",
      "code": "NC",
      "name": "North Carolina"
    },
    {
      "id": 100,
      "iso": "US",
      "code": "ND",
      "name": "North Dakota"
    },
    {
      "id": 101,
      "iso": "US",
      "code": "OH",
      "name": "Ohio"
    },
    {
      "id": 102,
      "iso": "US",
      "code": "OK",
      "name": "Oklahoma"
    },
    {
      "id": 103,
      "iso": "US",
      "code": "OR",
      "name": "Oregon"
    },
    {
      "id": 104,
      "iso": "US",
      "code": "PA",
      "name": "Pennsylvania"
    },
    {
      "id": 105,
      "iso": "US",
      "code": "RI",
      "name": "Rhode Island"
    },
    {
      "id": 106,
      "iso": "US",
      "code": "SC",
      "name": "South Carolina"
    },
    {
      "id": 107,
      "iso": "US",
      "code": "SD",
      "name": "South Dakota"
    },
    {
      "id": 108,
      "iso": "US",
      "code": "TN",
      "name": "Tennessee"
    },
    {
      "id": 109,
      "iso": "US",
      "code": "TX",
      "name": "Texas"
    },
    {
      "id": 110,
      "iso": "US",
      "code": "UT",
      "name": "Utah"
    },
    {
      "id": 111,
      "iso": "US",
      "code": "VT",
      "name": "Vermont"
    },
    {
      "id": 112,
      "iso": "US",
      "code": "VA",
      "name": "Virginia"
    },
    {
      "id": 113,
      "iso": "US",
      "code": "WA",
      "name": "Washington"
    },
    {
      "id": 114,
      "iso": "US",
      "code": "WV",
      "name": "West Virginia"
    },
    {
      "id": 115,
      "iso": "US",
      "code": "WI",
      "name": "Wisconsin"
    },
    {
      "id": 116,
      "iso": "US",
      "code": "WY",
      "name": "Wyoming"
    },
    {
      "id": 117,
      "iso": "CY",
      "code": "LEFKOSA",
      "name": "Lefkosa"
    },
    {
      "id": 118,
      "iso": "CY",
      "code": "GAZIMAGUSA",
      "name": "Gazimagusa"
    },
    {
      "id": 119,
      "iso": "CY",
      "code": "GIRNE",
      "name": "Girne"
    },
    {
      "id": 120,
      "iso": "CY",
      "code": "GUZELYURT",
      "name": "Guzelyurt"
    },
    {
      "id": 121,
      "iso": "CY",
      "code": "ISKELE",
      "name": "Iskele"
    },
    {
      "id": 122,
      "iso": "CY",
      "code": "LEFKE",
      "name": "Lefke"
    },
    {
      "id": 123,
      "iso": "CY",
      "code": "FAMAGUSTA",
      "name": "Famagusta"
    },
    {
      "id": 124,
      "iso": "CY",
      "code": "KYRENIA",
      "name": "Kyrenia"
    },
    {
      "id": 125,
      "iso": "CY",
      "code": "LARNACA",
      "name": "Larnaca"
    },
    {
      "id": 126,
      "iso": "CY",
      "code": "LIMASSOL",
      "name": "Limassol"
    },
    {
      "id": 127,
      "iso": "CY",
      "code": "NICOSIA",
      "name": "Nicosia"
    },
    {
      "id": 128,
      "iso": "CY",
      "code": "PAPHOS",
      "name": "Paphos"
    },
    {
      "id": 129,
      "iso": "GE",
      "code": "TBILISI",
      "name": "Tbilisi"
    },
    {
      "id": 130,
      "iso": "GE",
      "code": "IMERETI",
      "name": "Imereti"
    },
    {
      "id": 131,
      "iso": "GE",
      "code": "AJARIA",
      "name": "Ajaria"
    },
    {
      "id": 132,
      "iso": "GE",
      "code": "KVEMO_KARTLI",
      "name": "Kvemo Kartli"
    },
    {
      "id": 133,
      "iso": "GE",
      "code": "SAMEGRELO_ZEMO_SVANETI",
      "name": "Samegrelo and Zemo Svaneti"
    },
    {
      "id": 134,
      "iso": "GE",
      "code": "KAKHETI",
      "name": "Kakheti"
    },
    {
      "id": 135,
      "iso": "GE",
      "code": "SHIDA_KARTLI",
      "name": "Shida Kartli"
    },
    {
      "id": 136,
      "iso": "GE",
      "code": "ABKHAZIA",
      "name": "Abkhazia"
    },
    {
      "id": 137,
      "iso": "GE",
      "code": "SAMTSKHE_JAVAKHETI",
      "name": "Samtskhe-Javakheti"
    },
    {
      "id": 138,
      "iso": "GE",
      "code": "GURIA",
      "name": "Guria"
    },
    {
      "id": 139,
      "iso": "GE",
      "code": "MTSKHETA_MTIANETI",
      "name": "Mtskheta-Mtianeti"
    },
    {
      "id": 140,
      "iso": "GE",
      "code": "RACHA_LECHKHUMI_KVEMO_SVANETI",
      "name": "Racha-Lechkhumi and Kvemo Svaneti"
    }
  ],
  "meta": {
    "pageSize": 0,
    "page": 0,
    "total": "140"
  }
}