Address Formats

Address formats provide country-specific metadata for building address forms. Each country has different required fields, postal code patterns, and subdivision (state/province) lists. Use this endpoint to build dynamic address forms that adapt to the selected country.

Base URL: https://api.hydrajs.dev

Endpoints

Method	Path	Auth	Description
GET	/v1/address-formats	Publishable	List address formats
GET	/v1/address-formats/{country_code}	Publishable	Get address format for a country

---

List address formats

GET /v1/address-formats

Returns address format metadata for all supported countries. Each entry includes the country code, name, and required fields. Use the detail endpoint to get subdivisions and postal code patterns.

Request

curl https://api.hydrajs.dev/v1/address-formats \
  -H "Authorization: Bearer pk_live_YOUR_KEY"

Response 200

{
	"data": [
		{
			"country_code": "US",
			"country_name": "United States",
			"required_fields": ["address", "city", "state", "postal_code"]
		},
		{
			"country_code": "GB",
			"country_name": "United Kingdom",
			"required_fields": ["address", "city", "postal_code"]
		},
		{
			"country_code": "JP",
			"country_name": "Japan",
			"required_fields": ["address", "city", "state", "postal_code"]
		}
	]
}

---

Get address format for a country

GET /v1/address-formats/{country_code}

Returns detailed address format metadata for a specific country, including required fields, postal code regex, field labels, and subdivision list.

Path parameters

Parameter	Type	Description
country_code	string	ISO 3166-1 alpha-2 code (e.g. "US")

Request

curl https://api.hydrajs.dev/v1/address-formats/US \
  -H "Authorization: Bearer pk_live_YOUR_KEY"

Response 200

{
	"data": {
		"country_code": "US",
		"country_name": "United States",
		"format": "%N%n%O%n%A%n%C, %S %Z",
		"required_fields": ["address", "city", "state", "postal_code"],
		"uppercase_fields": ["city", "state"],
		"postal_code_pattern": "(\\d{5})(?:[ \\-](\\d{4}))?",
		"postal_code_example": "95014, 22162-1010",
		"labels": {
			"city": "city",
			"state": "state",
			"postal_code": "zip"
		},
		"subdivisions": [
			{ "code": "AL", "name": "Alabama" },
			{ "code": "AK", "name": "Alaska" },
			{ "code": "CA", "name": "California" }
		]
	}
}

---

The address format object

Field	Type	Description
country_code	string	ISO 3166-1 alpha-2 country code
country_name	string	Country display name
format	string	Address formatting template (detail endpoint only)
required_fields	string[]	Fields required for this country
uppercase_fields	string[]	Fields that should be uppercased (detail endpoint only)
postal_code_pattern	string	Regex pattern for postal code validation
postal_code_example	string	Example postal code(s)
labels	object	Country-specific field labels (city, state, postal_code)
subdivisions	array	State/province list with code and name