SearchCtrl+K

APIs/Administrative Units API

Administrative Units API - Get Country Subdivisions & Admin Units

The Administrative Units API gives you direct, structured access to country-level administrative division data, covering admin levels, admin units, and detailed administrative unit information for countries across the world. It delivers administrative unit names, codes, levels, ISO alpha-2 country codes, and country names using standard ISO 3166-1 alpha-2 country codes.

Use this Country Administrative Data API to build location-aware products that go deeper than just countries and cities. It powers address validation systems, tax and compliance tools, regional analytics dashboards, government data systems, and any application that needs to work with country subdivisions, administrative boundaries, and division-level geographic data at scale.

Try Playground Get Free API Key

10K Free Credits, No Credit Card Required

What You Get Across All Endpoints

Admin Levels by Country

Retrieve all administrative division levels available for a country using its ISO 3166-1 alpha-2 country code. Understand the full administrative hierarchy before querying specific units or subdivisions within it.

Admin Units by Country and Level

Find administrative units for a country and filter results by one or more administrative levels using the optional adminLevels parameter as a comma-separated list. Get exactly the subdivision data your application needs without pulling unnecessary records.

Detailed Admin Unit Information

Fetch complete details for a specific administrative unit using the admin_unit code. The response includes the unit name, admin code, admin level, ISO alpha-2 country code, and country name - everything needed for a full administrative unit record.

ISO Country Code Based Lookups

All endpoints use ISO 3166-1 alpha-2 country codes as the primary lookup key, ensuring standardized and consistent administrative data retrieval across every country and territory worldwide.

Hierarchical Administrative Data

Navigate country administrative hierarchies from top-level divisions down to specific units. Use admin level filtering to retrieve exactly the tier of administrative data your application requires.

Multiple Response Formats

Supports both json and xml response formats via the format parameter, giving your team the flexibility to integrate administrative unit data into any stack from modern web applications to enterprise and legacy systems.

API Endpoints

Admin Levels List API

Retrieve all administrative division levels defined for a country. Use this endpoint first to understand a country's hierarchy before querying its units.

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

Test

Explore the complete API reference with detailed request parameters, response fields, error codes, and code examples visit API Reference.

LANGUAGE


$ pip install requests
import requests 

url = "https://api.apifreaks.com/v1.0/geo/admin-levels?country=US"

payload = {}
headers = {
	'X-apiKey': 'API-KEY'
}

response = requests.request("GET", url, headers=headers, data=payload)

print(response.text)

Admin Units List API

Retrieve all administrative units for a country, with optional filtering by one or more admin levels via the adminLevels parameter.

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

Test

Explore the complete API reference with detailed request parameters, response fields, error codes, and code examples visit API Reference.

LANGUAGE


$ pip install requests
import requests 

url = "https://api.apifreaks.com/v1.0/geo/admin-units?country=US"

payload = {}
headers = {
	'X-apiKey': 'API-KEY'
}

response = requests.request("GET", url, headers=headers, data=payload)

print(response.text)

Admin Unit Details API

Fetch complete details for a specific administrative unit using its admin_unit code and country code.

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

Test

Explore the complete API reference with detailed request parameters, response fields, error codes, and code examples visit API Reference.

LANGUAGE


$ pip install requests
import requests 

url = "https://api.apifreaks.com/v1.0/geo/admin-unit/details?country=US&admin_unit=CA"

payload = {}
headers = {
	'X-apiKey': 'API-KEY'
}

response = requests.request("GET", url, headers=headers, data=payload)

print(response.text)

How-to Guides

Complete Country Admin Levels Data

Retrieve all administrative levels defined for a country to understand its geographic hierarchy before exploring its subdivisions.

curl -X 'GET' 'https://api.apifreaks.com/v1.0/geo/admin-levels?country=US&apiKey=API-KEY'

# Response
{
  "admin_levels": [
    "outlying area",
    "district",
    "state",
    "military postal region"
  ]
}

Find Administrative Units By Country Code

Use a country code to retrieve all administrative units for that country. Use the optional adminLevels parameter to filter results by one or more specific levels.

curl -X 'GET' 'https://api.apifreaks.com/v1.0/geo/admin-units?country=US&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"
    }
  ]
}

Extract Specific Administrative Unit Details

Use a country code and a specific admin unit code to retrieve a complete administrative unit record including its name, admin code, admin level, ISO alpha-2 country code, and country name.

curl -X 'GET' 'https://api.apifreaks.com/v1.0/geo/admin-unit/details?country=US&admin_unit=CA&apiKey=API-KEY'

# Response
{
  "name": "California",
  "admin_code": "CA",
  "admin_iso3166_2": "US-CA",
  "admin_level": "state",
  "country_iso3166_2": "US",
  "country_name": "United States"
}

Frequently Asked Questions

An Administrative Units API (often called a Country Subdivisions API) is a service that provides structured access to country-level administrative division data. It allows developers to retrieve administrative levels, administrative units, and detailed subdivision information for countries around the world through HTTP requests, without needing to maintain static administrative datasets or build geographic hierarchy systems from scratch.

Administrative levels refer to the tiers within a country's administrative hierarchy such as state, county, or municipality. Administrative units are the actual named divisions that exist at each of those levels - for example, California at the state level or Los Angeles County at the county level. The Administrative Units API provides separate endpoints for retrieving both, giving you full control over how you navigate a country's administrative structure.

The API uses ISO 3166-1 alpha-2 country codes. These are standardized two-letter country codes such as US for the United States, GB for the United Kingdom, and DE for Germany. Passing a full country name or an unsupported format will return a 400 Bad Request error indicating that only ISO 3166-1 alpha-2 codes are supported.

Yes. The admin units endpoint accepts an optional adminLevels parameter that takes a comma-separated list of administrative levels to filter results. For example, passing adminLevels=state returns only state-level units for the specified country, while passing adminLevels=state,county returns units at both levels in a single response.

If no administrative units are found for the specified country or admin unit code, the API returns a 404 response. This can occur when the country code is valid but no administrative data is available for that country in the dataset. In such cases it is recommended to first confirm what administrative levels are available for the country using the admin levels endpoint before querying units or details.

Pricing

To use the Administrative Units API, you will need API credits. We only charge for successful queries, defined by a 2xx status code. If your request results in a 4xx or 5xx status code, no credits will be charged, and any deducted credits will be returned.

For each successful request, 1 credit will be charged.

Utilize the Credits Usage API to efficiently monitor your recent consumption of both one-off and subscription credits. This API provides a streamlined way to track and manage your credit usage, ensuring you stay informed about your remaining balance and can optimize your resource allocation effectively.

Price Estimation Calculator

APIs/Administrative Units API

Administrative Units API - Get Country Subdivisions & Admin Units

Try Playground Get Free API Key

10K Free Credits, No Credit Card Required

What You Get Across All Endpoints

Admin Levels by Country

Admin Units by Country and Level

Detailed Admin Unit Information

ISO Country Code Based Lookups

All endpoints use ISO 3166-1 alpha-2 country codes as the primary lookup key, ensuring standardized and consistent administrative data retrieval across every country and territory worldwide.

Hierarchical Administrative Data

Navigate country administrative hierarchies from top-level divisions down to specific units. Use admin level filtering to retrieve exactly the tier of administrative data your application requires.

Multiple Response Formats

API Endpoints

Admin Levels List API

Retrieve all administrative division levels defined for a country. Use this endpoint first to understand a country's hierarchy before querying its units.

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

Test

Explore the complete API reference with detailed request parameters, response fields, error codes, and code examples visit API Reference.

LANGUAGE


$ pip install requests
import requests 

url = "https://api.apifreaks.com/v1.0/geo/admin-levels?country=US"

payload = {}
headers = {
	'X-apiKey': 'API-KEY'
}

response = requests.request("GET", url, headers=headers, data=payload)

print(response.text)

Admin Units List API

Retrieve all administrative units for a country, with optional filtering by one or more admin levels via the adminLevels parameter.

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

Test

Explore the complete API reference with detailed request parameters, response fields, error codes, and code examples visit API Reference.

LANGUAGE


$ pip install requests
import requests 

url = "https://api.apifreaks.com/v1.0/geo/admin-units?country=US"

payload = {}
headers = {
	'X-apiKey': 'API-KEY'
}

response = requests.request("GET", url, headers=headers, data=payload)

print(response.text)

Admin Unit Details API

Fetch complete details for a specific administrative unit using its admin_unit code and country code.

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

Test

Explore the complete API reference with detailed request parameters, response fields, error codes, and code examples visit API Reference.

LANGUAGE


$ pip install requests
import requests 

url = "https://api.apifreaks.com/v1.0/geo/admin-unit/details?country=US&admin_unit=CA"

payload = {}
headers = {
	'X-apiKey': 'API-KEY'
}

response = requests.request("GET", url, headers=headers, data=payload)

print(response.text)

How-to Guides

Complete Country Admin Levels Data

Retrieve all administrative levels defined for a country to understand its geographic hierarchy before exploring its subdivisions.

curl -X 'GET' 'https://api.apifreaks.com/v1.0/geo/admin-levels?country=US&apiKey=API-KEY'

# Response
{
  "admin_levels": [
    "outlying area",
    "district",
    "state",
    "military postal region"
  ]
}

Find Administrative Units By Country Code

Use a country code to retrieve all administrative units for that country. Use the optional adminLevels parameter to filter results by one or more specific levels.

curl -X 'GET' 'https://api.apifreaks.com/v1.0/geo/admin-units?country=US&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"
    }
  ]
}

Extract Specific Administrative Unit Details

Use a country code and a specific admin unit code to retrieve a complete administrative unit record including its name, admin code, admin level, ISO alpha-2 country code, and country name.

curl -X 'GET' 'https://api.apifreaks.com/v1.0/geo/admin-unit/details?country=US&admin_unit=CA&apiKey=API-KEY'

# Response
{
  "name": "California",
  "admin_code": "CA",
  "admin_iso3166_2": "US-CA",
  "admin_level": "state",
  "country_iso3166_2": "US",
  "country_name": "United States"
}

Frequently Asked Questions

Pricing

For each successful request, 1 credit will be charged.

Administrative Units API - Get Country Subdivisions & Admin Units

What You Get Across All Endpoints

Admin Levels by Country

Admin Units by Country and Level

Detailed Admin Unit Information

ISO Country Code Based Lookups

Hierarchical Administrative Data

Multiple Response Formats

API Endpoints

Admin Levels List API

Admin Units List API

Admin Unit Details API

How-to Guides

Complete Country Admin Levels Data

Find Administrative Units By Country Code

Extract Specific Administrative Unit Details

Frequently Asked Questions

What is an Administrative Units API?

What is the difference between admin levels and admin units?

What country code format does the Administrative Units API use?

Can I filter administrative units by a specific level?

What happens if no administrative units are found for a country?

Pricing

Price Estimation Calculator

Administrative Units API - Get Country Subdivisions & Admin Units

What You Get Across All Endpoints

Admin Levels by Country

Admin Units by Country and Level

Detailed Admin Unit Information

ISO Country Code Based Lookups

Hierarchical Administrative Data

Multiple Response Formats

API Endpoints

Admin Levels List API

Admin Units List API

Admin Unit Details API

How-to Guides

Complete Country Admin Levels Data

Find Administrative Units By Country Code

Extract Specific Administrative Unit Details

Frequently Asked Questions

What is an Administrative Units API?

What is the difference between admin levels and admin units?

What country code format does the Administrative Units API use?

Can I filter administrative units by a specific level?

What happens if no administrative units are found for a country?

Pricing

Price Estimation Calculator