SearchCtrl+K

APIs/Geography APIs/Administrative Units API/Reference

Administrative Units API Reference

Retrieve administrative units - states, provinces, governorates - for any country using ISO 3166-1 alpha-2 country codes. Supports optional filtering by one or more admin levels.

GEThttps://api.apifreaks.com/v1.0/geo/admin-units

Test

Returns all administrative units for a country, optionally filtered by admin level using the adminLevels parameter.

Getting Started

Authentication

Authorize every request with your API key, passed either as a header or as a query parameter:

Header - X-apiKey
Query parameter - apiKey

API Version

This is version v1.0 of the API.

LANGUAGE

curl -X 'GET' \
  'https://api.apifreaks.com/v1.0/geo/admin-units?country=PK' \
  -H 'X-apiKey: API-KEY'

Response

{
  "admin_units": [
    {
      "name": "Alabama",
      "admin_code": "AL",
      "admin_level": "state"
    },
    {
      "name": "Alaska",
      "admin_code": "AK",
      "admin_level": "state"
    },
    {
      "name": "American Samoa",
      "admin_code": "AS",
      "admin_level": "outlying area"
    },
    {
      "name": "Arizona",
      "admin_code": "AZ",
      "admin_level": "state"
    },
    {
      "name": "Arkansas",
      "admin_code": "AR",
      "admin_level": "state"
    },
    {
      "name": "Armed Forces Europe",
      "admin_code": "AE",
      "admin_level": "military postal region"
    },
    {
      "name": "Armed Forces of the Americas",
      "admin_code": "AA",
      "admin_level": "military postal region"
    },
    {
      "name": "Armed Forces Pacific",
      "admin_code": "AP",
      "admin_level": "military postal region"
    },
    {
      "name": "California",
      "admin_code": "CA",
      "admin_level": "state"
    },
    {
      "name": "Colorado",
      "admin_code": "CO",
      "admin_level": "state"
    },
    {
      "name": "Connecticut",
      "admin_code": "CT",
      "admin_level": "state"
    },
    {
      "name": "Delaware",
      "admin_code": "DE",
      "admin_level": "state"
    },
    {
      "name": "District of Columbia",
      "admin_code": "DC",
      "admin_level": "district"
    },
    {
      "name": "Florida",
      "admin_code": "FL",
      "admin_level": "state"
    },
    {
      "name": "Georgia",
      "admin_code": "GA",
      "admin_level": "state"
    },
    {
      "name": "Guam",
      "admin_code": "GU",
      "admin_level": "outlying area"
    },
    {
      "name": "Hawaii",
      "admin_code": "HI",
      "admin_level": "state"
    },
    {
      "name": "Idaho",
      "admin_code": "ID",
      "admin_level": "state"
    },
    {
      "name": "Illinois",
      "admin_code": "IL",
      "admin_level": "state"
    },
    {
      "name": "Indiana",
      "admin_code": "IN",
      "admin_level": "state"
    },
    {
      "name": "Iowa",
      "admin_code": "IA",
      "admin_level": "state"
    },
    {
      "name": "Kansas",
      "admin_code": "KS",
      "admin_level": "state"
    },
    {
      "name": "Kentucky",
      "admin_code": "KY",
      "admin_level": "state"
    },
    {
      "name": "Louisiana",
      "admin_code": "LA",
      "admin_level": "state"
    },
    {
      "name": "Maine",
      "admin_code": "ME",
      "admin_level": "state"
    },
    {
      "name": "Maryland",
      "admin_code": "MD",
      "admin_level": "state"
    },
    {
      "name": "Massachusetts",
      "admin_code": "MA",
      "admin_level": "state"
    },
    {
      "name": "Michigan",
      "admin_code": "MI",
      "admin_level": "state"
    },
    {
      "name": "Minnesota",
      "admin_code": "MN",
      "admin_level": "state"
    },
    {
      "name": "Mississippi",
      "admin_code": "MS",
      "admin_level": "state"
    },
    {
      "name": "Missouri",
      "admin_code": "MO",
      "admin_level": "state"
    },
    {
      "name": "Montana",
      "admin_code": "MT",
      "admin_level": "state"
    },
    {
      "name": "Nebraska",
      "admin_code": "NE",
      "admin_level": "state"
    },
    {
      "name": "Nevada",
      "admin_code": "NV",
      "admin_level": "state"
    },
    {
      "name": "New Hampshire",
      "admin_code": "NH",
      "admin_level": "state"
    },
    {
      "name": "New Jersey",
      "admin_code": "NJ",
      "admin_level": "state"
    },
    {
      "name": "New Mexico",
      "admin_code": "NM",
      "admin_level": "state"
    },
    {
      "name": "New York",
      "admin_code": "NY",
      "admin_level": "state"
    },
    {
      "name": "North Carolina",
      "admin_code": "NC",
      "admin_level": "state"
    },
    {
      "name": "North Dakota",
      "admin_code": "ND",
      "admin_level": "state"
    },
    {
      "name": "Northern Mariana Islands",
      "admin_code": "MP",
      "admin_level": "outlying area"
    },
    {
      "name": "Ohio",
      "admin_code": "OH",
      "admin_level": "state"
    },
    {
      "name": "Oklahoma",
      "admin_code": "OK",
      "admin_level": "state"
    },
    {
      "name": "Oregon",
      "admin_code": "OR",
      "admin_level": "state"
    },
    {
      "name": "Pennsylvania",
      "admin_code": "PA",
      "admin_level": "state"
    },
    {
      "name": "Puerto Rico",
      "admin_code": "PR",
      "admin_level": "outlying area"
    },
    {
      "name": "Rhode Island",
      "admin_code": "RI",
      "admin_level": "state"
    },
    {
      "name": "South Carolina",
      "admin_code": "SC",
      "admin_level": "state"
    },
    {
      "name": "South Dakota",
      "admin_code": "SD",
      "admin_level": "state"
    },
    {
      "name": "Tennessee",
      "admin_code": "TN",
      "admin_level": "state"
    },
    {
      "name": "Texas",
      "admin_code": "TX",
      "admin_level": "state"
    },
    {
      "name": "United States Minor Outlying Islands",
      "admin_code": "UM",
      "admin_level": "outlying area"
    },
    {
      "name": "United States Virgin Islands",
      "admin_code": "VI",
      "admin_level": "outlying area"
    },
    {
      "name": "Utah",
      "admin_code": "UT",
      "admin_level": "state"
    },
    {
      "name": "Vermont",
      "admin_code": "VT",
      "admin_level": "state"
    },
    {
      "name": "Virginia",
      "admin_code": "VA",
      "admin_level": "state"
    },
    {
      "name": "Washington",
      "admin_code": "WA",
      "admin_level": "state"
    },
    {
      "name": "West Virginia",
      "admin_code": "WV",
      "admin_level": "state"
    },
    {
      "name": "Wisconsin",
      "admin_code": "WI",
      "admin_level": "state"
    },
    {
      "name": "Wyoming",
      "admin_code": "WY",
      "admin_level": "state"
    }
  ]
}

API Request

Query Parameters

The following parameters can be used in your API requests.

formatoptionalStringdefault: json

Response format: 'json' (default) or 'xml'.

countryrequiredString

Country code in ISO 3166-1 alpha-2 format.

admin_leveloptionalString

Comma-separated list to filter results by one or more administrative levels.

API Response Schema

A successful request returns a 200 OK response with an array of admin unit objects.

An array of administrative unit objects for the specified country, optionally filtered by admin level.

Custom Response Headers

Besides the response body, every response carries custom headers you can use to track credit usage, and concurrency usage on endpoints that enforce a concurrency limit. See the Custom Response Headers documentation and the endpoints with concurrency limits for more details.

X-Concurrent-Threadsheaderconcurrency-limited endpoints

Specifies the maximum number of concurrent requests allowed.

X-Concurrent-Threads-Activeheaderconcurrency-limited endpoints

Indicates the number of active concurrent requests being processed.

X-AF-Credits-Costheaderall responses

Specifies the number of credits consumed by the current request.

Error Status & Codes

See the HTTP Status Codes documentation for a complete reference of common API errors and HTTP status codes.

400

Only ISO 3166-1 alpha-2 codes country codes are supported.

404

This Country does not have any admin units associated with it.

Administrative Units API Reference

Retrieve administrative units - states, provinces, governorates - for any country using ISO 3166-1 alpha-2 country codes. Supports optional filtering by one or more admin levels.

GEThttps://api.apifreaks.com/v1.0/geo/admin-units

Test

Returns all administrative units for a country, optionally filtered by admin level using the adminLevels parameter.

Getting Started

Authentication

Authorize every request with your API key, passed either as a header or as a query parameter:

Header - X-apiKey
Query parameter - apiKey

API Version

This is version v1.0 of the API.

LANGUAGE

curl -X 'GET' \
  'https://api.apifreaks.com/v1.0/geo/admin-units?country=PK' \
  -H 'X-apiKey: API-KEY'

Response

{
  "admin_units": [
    {
      "name": "Alabama",
      "admin_code": "AL",
      "admin_level": "state"
    },
    {
      "name": "Alaska",
      "admin_code": "AK",
      "admin_level": "state"
    },
    {
      "name": "American Samoa",
      "admin_code": "AS",
      "admin_level": "outlying area"
    },
    {
      "name": "Arizona",
      "admin_code": "AZ",
      "admin_level": "state"
    },
    {
      "name": "Arkansas",
      "admin_code": "AR",
      "admin_level": "state"
    },
    {
      "name": "Armed Forces Europe",
      "admin_code": "AE",
      "admin_level": "military postal region"
    },
    {
      "name": "Armed Forces of the Americas",
      "admin_code": "AA",
      "admin_level": "military postal region"
    },
    {
      "name": "Armed Forces Pacific",
      "admin_code": "AP",
      "admin_level": "military postal region"
    },
    {
      "name": "California",
      "admin_code": "CA",
      "admin_level": "state"
    },
    {
      "name": "Colorado",
      "admin_code": "CO",
      "admin_level": "state"
    },
    {
      "name": "Connecticut",
      "admin_code": "CT",
      "admin_level": "state"
    },
    {
      "name": "Delaware",
      "admin_code": "DE",
      "admin_level": "state"
    },
    {
      "name": "District of Columbia",
      "admin_code": "DC",
      "admin_level": "district"
    },
    {
      "name": "Florida",
      "admin_code": "FL",
      "admin_level": "state"
    },
    {
      "name": "Georgia",
      "admin_code": "GA",
      "admin_level": "state"
    },
    {
      "name": "Guam",
      "admin_code": "GU",
      "admin_level": "outlying area"
    },
    {
      "name": "Hawaii",
      "admin_code": "HI",
      "admin_level": "state"
    },
    {
      "name": "Idaho",
      "admin_code": "ID",
      "admin_level": "state"
    },
    {
      "name": "Illinois",
      "admin_code": "IL",
      "admin_level": "state"
    },
    {
      "name": "Indiana",
      "admin_code": "IN",
      "admin_level": "state"
    },
    {
      "name": "Iowa",
      "admin_code": "IA",
      "admin_level": "state"
    },
    {
      "name": "Kansas",
      "admin_code": "KS",
      "admin_level": "state"
    },
    {
      "name": "Kentucky",
      "admin_code": "KY",
      "admin_level": "state"
    },
    {
      "name": "Louisiana",
      "admin_code": "LA",
      "admin_level": "state"
    },
    {
      "name": "Maine",
      "admin_code": "ME",
      "admin_level": "state"
    },
    {
      "name": "Maryland",
      "admin_code": "MD",
      "admin_level": "state"
    },
    {
      "name": "Massachusetts",
      "admin_code": "MA",
      "admin_level": "state"
    },
    {
      "name": "Michigan",
      "admin_code": "MI",
      "admin_level": "state"
    },
    {
      "name": "Minnesota",
      "admin_code": "MN",
      "admin_level": "state"
    },
    {
      "name": "Mississippi",
      "admin_code": "MS",
      "admin_level": "state"
    },
    {
      "name": "Missouri",
      "admin_code": "MO",
      "admin_level": "state"
    },
    {
      "name": "Montana",
      "admin_code": "MT",
      "admin_level": "state"
    },
    {
      "name": "Nebraska",
      "admin_code": "NE",
      "admin_level": "state"
    },
    {
      "name": "Nevada",
      "admin_code": "NV",
      "admin_level": "state"
    },
    {
      "name": "New Hampshire",
      "admin_code": "NH",
      "admin_level": "state"
    },
    {
      "name": "New Jersey",
      "admin_code": "NJ",
      "admin_level": "state"
    },
    {
      "name": "New Mexico",
      "admin_code": "NM",
      "admin_level": "state"
    },
    {
      "name": "New York",
      "admin_code": "NY",
      "admin_level": "state"
    },
    {
      "name": "North Carolina",
      "admin_code": "NC",
      "admin_level": "state"
    },
    {
      "name": "North Dakota",
      "admin_code": "ND",
      "admin_level": "state"
    },
    {
      "name": "Northern Mariana Islands",
      "admin_code": "MP",
      "admin_level": "outlying area"
    },
    {
      "name": "Ohio",
      "admin_code": "OH",
      "admin_level": "state"
    },
    {
      "name": "Oklahoma",
      "admin_code": "OK",
      "admin_level": "state"
    },
    {
      "name": "Oregon",
      "admin_code": "OR",
      "admin_level": "state"
    },
    {
      "name": "Pennsylvania",
      "admin_code": "PA",
      "admin_level": "state"
    },
    {
      "name": "Puerto Rico",
      "admin_code": "PR",
      "admin_level": "outlying area"
    },
    {
      "name": "Rhode Island",
      "admin_code": "RI",
      "admin_level": "state"
    },
    {
      "name": "South Carolina",
      "admin_code": "SC",
      "admin_level": "state"
    },
    {
      "name": "South Dakota",
      "admin_code": "SD",
      "admin_level": "state"
    },
    {
      "name": "Tennessee",
      "admin_code": "TN",
      "admin_level": "state"
    },
    {
      "name": "Texas",
      "admin_code": "TX",
      "admin_level": "state"
    },
    {
      "name": "United States Minor Outlying Islands",
      "admin_code": "UM",
      "admin_level": "outlying area"
    },
    {
      "name": "United States Virgin Islands",
      "admin_code": "VI",
      "admin_level": "outlying area"
    },
    {
      "name": "Utah",
      "admin_code": "UT",
      "admin_level": "state"
    },
    {
      "name": "Vermont",
      "admin_code": "VT",
      "admin_level": "state"
    },
    {
      "name": "Virginia",
      "admin_code": "VA",
      "admin_level": "state"
    },
    {
      "name": "Washington",
      "admin_code": "WA",
      "admin_level": "state"
    },
    {
      "name": "West Virginia",
      "admin_code": "WV",
      "admin_level": "state"
    },
    {
      "name": "Wisconsin",
      "admin_code": "WI",
      "admin_level": "state"
    },
    {
      "name": "Wyoming",
      "admin_code": "WY",
      "admin_level": "state"
    }
  ]
}

API Request

Query Parameters

The following parameters can be used in your API requests.

formatoptionalStringdefault: json

Response format: 'json' (default) or 'xml'.

countryrequiredString

Country code in ISO 3166-1 alpha-2 format.

admin_leveloptionalString

Comma-separated list to filter results by one or more administrative levels.

API Response Schema

A successful request returns a 200 OK response with an array of admin unit objects.

An array of administrative unit objects for the specified country, optionally filtered by admin level.

Custom Response Headers

X-Concurrent-Threadsheaderconcurrency-limited endpoints

Specifies the maximum number of concurrent requests allowed.

X-Concurrent-Threads-Activeheaderconcurrency-limited endpoints

Indicates the number of active concurrent requests being processed.

X-AF-Credits-Costheaderall responses

Specifies the number of credits consumed by the current request.

Error Status & Codes

See the HTTP Status Codes documentation for a complete reference of common API errors and HTTP status codes.

400

Only ISO 3166-1 alpha-2 codes country codes are supported.

404

This Country does not have any admin units associated with it.

Quick Links

Quick Links

Administrative Units API Reference

Getting Started

Authentication

API Version

API Request

Query Parameters

API Response Schema

Custom Response Headers

Error Status & Codes

Quick Links

Quick Links

Administrative Units API Reference

Getting Started

Authentication

API Version

API Request

Query Parameters

API Response Schema

Custom Response Headers

Error Status & Codes

Administrative Units API Reference

Getting Started

Authentication

API Version

API Request

Query Parameters

API Response Schema

Custom Response Headers

Error Status & Codes

More APIs in This Category

Admin Levels API

Admin Units Details API

Countries API

Country Details API

Cities API

Regions API

Subregions API

Flags API

Supported Flags API

Administrative Units API Reference

Getting Started

Authentication

API Version

API Request

Query Parameters

API Response Schema

Custom Response Headers

Error Status & Codes

More APIs in This Category

Admin Levels API

Admin Units Details API

Countries API

Country Details API

Cities API

Regions API

Subregions API

Flags API

Supported Flags API