ZipCodeResponse

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://raw.githubusercontent.com/api-evangelist/metadapi/main/json-schema/metadapi-zip-code-response-schema.json",
  "title": "ZipCodeResponse",
  "description": "Succesful response of the ",
  "x-generated": "2026-10-20",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/metadapi-zipcode-openapi.json#/components/schemas/ZipCodeResponse",
  "type": "object",
  "properties": {
    "links": {
      "$ref": "#/$defs/Links"
    },
    "meta": {
      "$ref": "#/$defs/meta"
    },
    "data": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/Zipcode"
      }
    }
  },
  "$defs": {
    "Links": {
      "title": "links",
      "type": "object",
      "description": "API Response Links",
      "properties": {
        "self": {
          "type": "string",
          "description": "Link to this response."
        },
        "first": {
          "type": "string",
          "description": "Link to the first group of records from API call."
        },
        "next": {
          "type": "string",
          "description": "Link to next set of results from API call."
        },
        "prev": {
          "type": "string",
          "description": "Link to the previous set of records from API call."
        },
        "last": {
          "type": "string",
          "description": "Link to last set of records from API call. "
        }
      }
    },
    "Zipcode": {
      "description": "Zip Code Data Model",
      "type": "object",
      "title": "Zip Code",
      "properties": {
        "zipCode": {
          "type": "string",
          "minLength": 5,
          "maxLength": 5,
          "description": "5 Digit Zip Code. Zone Improvement Plan."
        },
        "uspsMainCityKey": {
          "type": "string",
          "minLength": 1,
          "description": "USPS City / Town key identifier for the main city of the zip code."
        },
        "uspsMainCityName": {
          "type": "string",
          "minLength": 1,
          "description": "USPS City / Town Name for the main city of the zip code. USPS Upper Case Format."
        },
        "titleCaseCityName": {
          "type": "string",
          "minLength": 1,
          "description": "USPS City / Town Name for the main city of the zip code. Title Case Format."
        },
        "zipClassificationCode": {
          "type": [
            "string",
            "null"
          ],
          "minLength": 1,
          "description": "Code provided by USPS for the type of Zip Code it represents.  P = PO Box Zip, U = Unique Zip, M = APO/FPO Military Zip , null (not provided by USPS),N = Non-Unique Zip."
        },
        "zipClassificationDesc": {
          "type": "string",
          "minLength": 1,
          "description": "Description of the zip classification code.   P = PO Box Zip, U = Unique Zip, M = APO/FPO Military Zip , null (not provided by USPS), = Non-Unique Zip."
        },
        "uspsFacilityCode": {
          "type": "string",
          "minLength": 1,
          "description": "Facility code provided by the USPS. B=Branch, C=Community Post Office, N = Non-Postal Community Name, former postal facility or place name, P= Post Office, S=Station, U = Urbanization"
        },
        "uspsFacilityName": {
          "type": "string",
          "minLength": 1,
          "description": "USPS Facility Name  B=Branch, C=Community Post Office, N = Non-Postal Community Name, former postal facility or place name, P= Post Office, S=Station, U = Urbanization"
        },
        "uspsCityMailingInd": {
          "type": "boolean",
          "description": "City names with the City State Mailing Name indicator flag set to True are considered part of a complete and standardized address; city names with the flag set to false  file should not be used in a complete and standardized address."
        },
        "uspsDeliveryCode": {
          "type": "string",
          "minLength": 1,
          "description": "Determines if the zip code city has Carrier Routes."
        },
        "uspsDeliveryDesc": {
          "type": "string",
          "minLength": 1,
          "description": "Determines if the zip code city has Carrier Routes."
        },
        "uspsCarrierRouteSortCode": {
          "type": "string",
          "minLength": 1,
          "description": "Code for the available carrier route."
        },
        "uspsCarrierRouteRateSortDesc": {
          "type": "string",
          "minLength": 1,
          "description": "Description for the carrier route code."
        },
        "uniqueZipNameInd": {
          "type": "boolean",
          "description": "True = Unique Zip Code Name. False the zip code name is not unique."
        },
        "uspsFinanceNumber": {
          "type": "string",
          "minLength": 1,
          "description": "USPS Provided Finance Number. This code is assigned to postal service facilities."
        },
        "stateCode": {
          "type": "string",
          "minLength": 1,
          "description": "Standard 2 character state code."
        },
        "stateName": {
          "type": "string",
          "minLength": 1,
          "description": "State Name"
        },
        "stateFipsCode": {
          "type": "string",
          "minLength": 1,
          "description": "Federal Information Processing Standards 2 digit assigned code."
        },
        "stateAbbr": {
          "type": "string",
          "minLength": 1,
          "description": "Abbreviation for state name."
        },
        "countyFipsCode": {
          "type": "string",
          "minLength": 1,
          "description": "FIPS code assigned to the county of the main city of the zip code."
        },
        "uspsCountyName": {
          "type": "string",
          "minLength": 1,
          "description": "Name of the county of the main city for the zip code."
        },
        "titleCaseCountyName": {
          "type": "string",
          "minLength": 1,
          "description": "Main County Name in Title Case"
        },
        "latitude": {
          "type": [
            "number",
            "null"
          ],
          "description": "Zip Code Latitude"
        },
        "longitude": {
          "type": [
            "number",
            "null"
          ],
          "description": "Zip Code Longitude"
        },
        "landAreaMi2": {
          "type": [
            "number",
            "null"
          ],
          "description": "Zip Code Land area in Square Miles"
        },
        "waterAreaMi2": {
          "type": [
            "number",
            "null"
          ],
          "description": "Zip Code Water Area in Square Miles"
        },
        "landAreaKm2": {
          "type": [
            "number",
            "null"
          ],
          "description": "Zip Code Land Area in square kilometers."
        },
        "waterAreaKm2": {
          "type": [
            "number",
            "null"
          ],
          "description": "Zip Code water area in Square kilometers."
        },
        "divisionCode": {
          "type": "string",
          "minLength": 1,
          "description": "Division Code. Part of the geographical hierarchy of the US provided by the united states census."
        },
        "divisionName": {
          "type": "string",
          "minLength": 1,
          "description": "Division Name. Part of the geographical hierarchy of the US provided by the united states census."
        },
        "regionCode": {
          "type": "string",
          "minLength": 1,
          "description": "Region Code. Part of the geographical hierarchy of the US provided by the united states census."
        },
        "regionName": {
          "type": "string",
          "minLength": 1,
          "description": "Region Name. Part of the geographical hierarchy of the US provided by the united states census."
        },
        "msaCode": {
          "type": "string",
          "minLength": 1,
          "description": "5 digit MSA (Metropolitan Statistical Area) code."
        },
        "msaName": {
          "type": "string",
          "minLength": 1,
          "description": "Name of the defined MSA code."
        },
        "cityAliases": {
          "type": "array",
          "uniqueItems": true,
          "minItems": 1,
          "description": "Array that contains all the city aliases for the given zip code.",
          "items": {
            "type": "object",
            "properties": {
              "uspsCityKey": {
                "type": "string",
                "minLength": 1,
                "description": "USPS City / Town key identifier city of the zip code."
              },
              "uspsCityName": {
                "type": "string",
                "minLength": 1,
                "description": "USPS City / Town Name for the zip code. All uppercase."
              },
              "titleCaseCityName": {
                "type": "string",
                "minLength": 1,
                "description": "USPS City / Town Name for the zip code."
              },
              "uspsCityAbbr": {
                "type": [
                  "string",
                  "null"
                ],
                "minLength": 1,
                "description": "Main city abbreviation provided by USPS. Null if not provided. Uppercase."
              },
              "uspsCityMailingInd": {
                "type": "boolean",
                "description": "City names with the City State Mailing Name indicator flag set to True are considered part of a complete and standardized address; city names with the flag set to false  file should not be used in a complete and standardized address."
              },
              "uspsMainCityInd": {
                "type": "boolean",
                "description": "If true, the city name and code is the main zip code city name.  (Preferred USPS city)."
              }
            },
            "required": [
              "uspsCityKey",
              "uspsCityName",
              "titleCaseCityName",
              "uspsCityAbbr",
              "uspsCityMailingInd",
              "uspsMainCityInd"
            ]
          }
        },
        "zipCodeStatistics": {
          "type": [
            "array",
            "null"
          ],
          "uniqueItems": true,
          "minItems": 1,
          "description": "Available statistics by year of the Zip Code.",
          "items": {
            "type": "object",
            "properties": {
              "year": {
                "type": "number",
                "description": "Year for the captured statistic"
              },
              "totalPopulation": {
                "type": "number",
                "description": "Total population of the zip code"
              },
              "malePopulation": {
                "type": "number",
                "description": "Total Male population of the zip code."
              },
              "femalePopulation": {
                "type": "number",
                "description": "Total female population of the zip code."
              }
            },
            "required": [
              "year",
              "totalPopulation",
              "malePopulation",
              "femalePopulation"
            ]
          }
        }
      },
      "required": [
        "zipCode",
        "uspsMainCityKey",
        "uspsMainCityName",
        "titleCaseCityName",
        "zipClassificationCode",
        "zipClassificationDesc",
        "uspsFacilityCode",
        "uspsFacilityName",
        "uspsCityMailingInd",
        "uspsDeliveryCode",
        "uspsDeliveryDesc",
        "uspsCarrierRouteSortCode",
        "uspsCarrierRouteRateSortDesc",
        "uniqueZipNameInd",
        "uspsFinanceNumber",
        "stateCode",
        "stateName",
        "stateFipsCode",
        "stateAbbr",
        "countyFipsCode",
        "uspsCountyName",
        "titleCaseCountyName",
        "landAreaMi2",
        "waterAreaMi2",
        "landAreaKm2",
        "waterAreaKm2",
        "divisionCode",
        "divisionName",
        "regionCode",
        "regionName",
        "msaCode",
        "msaName",
        "cityAliases",
        "zipCodeStatistics"
      ]
    },
    "meta": {
      "title": "meta",
      "type": "object",
      "description": "Response Metadata. Provides additional context about the data response.",
      "properties": {
        "count": {
          "type": "number",
          "description": "Total number of records of the response. Note: the data object always has a limit number of records retrieved."
        },
        "offset": {
          "type": "number",
          "description": "Offset position of where the first record returned."
        },
        "limit": {
          "type": "number",
          "description": "Total number of records returned in the data array. "
        }
      },
      "required": [
        "count",
        "offset",
        "limit"
      ]
    }
  }
}