@apifreaks/openapi-specs 0.1.0

package/specs/zip-code/zip-codes-by-city.json

@@ -0,0 +1,279 @@
+{
+  "openapi": "3.1.1",
+  "info": {
+    "title": "ZIP Codes Search by City API: Find ZIP Codes for Any City or State/Province/Region",
+    "version": "1.0.0",
+    "description": "Find all ZIP and postal codes for any city worldwide. Provide a city name and country code to retrieve the complete list of codes associated with that location. Supports an optional state_name filter for countries with administrative divisions. Results are paginated; each page returns the codes array plus total result count, total pages, current page, and current page size. An unrecognized city/country combination returns a 404, as does requesting a page beyond the available range.",
+    "contact": {
+      "name": "APIFreaks Support",
+      "url": "https://apifreaks.com/contact",
+      "email": "support@apifreaks.com"
+    }
+  },
+  "servers": [
+    {
+      "url": "https://api.apifreaks.com/v1.0",
+      "description": "ZIP Codes by City API Server"
+    }
+  ],
+  "paths": {
+    "/zipcode/search/city": {
+      "get": {
+        "tags": ["ZIP Code APIs"],
+        "summary": "Search ZIP/postal codes by city",
+        "description": "Returns every ZIP/postal code associated with the given city and country, optionally narrowed by state or province.",
+        "operationId": "searchZipByCity",
+        "parameters": [
+          {
+            "name": "format",
+            "in": "query",
+            "required": false,
+            "schema": {
+              "type": "string",
+              "enum": ["json", "xml"],
+              "default": "json"
+            },
+            "description": "Format of the response. Possible values: json, xml."
+          },
+          {
+            "name": "city",
+            "in": "query",
+            "required": true,
+            "schema": {
+              "type": "string"
+            },
+            "description": "Name of the city to find ZIP/postal codes for."
+          },
+          {
+            "name": "country",
+            "in": "query",
+            "required": true,
+            "schema": {
+              "type": "string"
+            },
+            "description": "Country code in ISO 3166-1 alpha-2 format."
+          },
+          {
+            "name": "state_name",
+            "in": "query",
+            "required": false,
+            "schema": {
+              "type": "string"
+            },
+            "description": "Name of the state or province associated with the country. Useful to disambiguate cities with the same name in different states."
+          },
+          {
+            "name": "page",
+            "in": "query",
+            "required": false,
+            "schema": {
+              "type": "integer",
+              "default": 1,
+              "minimum": 1
+            },
+            "description": "Page number to retrieve paginated results."
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "ZIP/postal codes retrieved successfully",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ZipcodeSearchCityResponse"
+                },
+                "examples": {
+                  "success": {
+                    "summary": "Codes for a city",
+                    "value": {
+                      "total_results": 368,
+                      "total_pages": 1,
+                      "current_page": 1,
+                      "current_page_size": 368,
+                      "codes": [
+                        "90001",
+                        "90002",
+                        "90003",
+                        "90210",
+                        "90211",
+                        "90212"
+                      ]
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "Bad Request — Missing city, invalid country code, or invalid page number",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                },
+                "examples": {
+                  "MissingCity": {
+                    "summary": "Missing required city parameter",
+                    "value": {
+                      "error": "Invalid Param Exception",
+                      "message": "please pass correct parameters",
+                      "path": "/v1.0/zipcode/search/city",
+                      "status": 400,
+                      "timestamp": "2026-07-27T11:22:48.293Z"
+                    }
+                  },
+                  "BadCountry": {
+                    "summary": "country is not a valid ISO 3166-1 alpha-2 code",
+                    "value": {
+                      "timestamp": "2026-07-27T11:22:59.112Z",
+                      "path": "/v1.0/zipcode/search/city",
+                      "status": 400,
+                      "error": "Invalid Country Code Provided",
+                      "message": "Only ISO 3166-1 alpha-2 codes country codes are supported."
+                    }
+                  },
+                  "BadPage": {
+                    "summary": "page is 0 or negative",
+                    "value": {
+                      "timestamp": "2026-07-27T11:22:59.742Z",
+                      "path": "/v1.0/zipcode/search/city",
+                      "status": 400,
+                      "error": "Invalid Page Number",
+                      "message": "The page number must be greater than 0."
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "404": {
+            "description": "Not Found — No codes for the city, or requested page is out of range",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                },
+                "examples": {
+                  "NotFound": {
+                    "summary": "No codes found for the given city/country",
+                    "value": {
+                      "timestamp": "2026-07-27T11:23:00.301Z",
+                      "path": "/v1.0/zipcode/search/city",
+                      "status": 404,
+                      "error": "Postal/Zip Codes Not Found",
+                      "message": "No postal/zip codes found for the provided city Nonexistentcityxyz123 in country US."
+                    }
+                  },
+                  "PageNotFound": {
+                    "summary": "Requested page exceeds total_pages",
+                    "value": {
+                      "timestamp": "2026-07-27T11:23:00.873Z",
+                      "path": "/v1.0/zipcode/search/city",
+                      "status": 404,
+                      "error": "Page Not Found",
+                      "message": "The requested page exceeds the available page range."
+                    }
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+  },
+  "components": {
+    "securitySchemes": {
+      "ApiKeyAuthHeader": {
+        "type": "apiKey",
+        "in": "header",
+        "name": "X-apiKey",
+        "description": "Pass your API key via the X-apiKey request header."
+      },
+      "ApiKeyAuthQuery": {
+        "type": "apiKey",
+        "in": "query",
+        "name": "apiKey",
+        "description": "Pass your API key via the apiKey query parameter."
+      }
+    },
+    "schemas": {
+      "ZipcodeSearchCityResponse": {
+        "type": "object",
+        "description": "ZIP/postal codes for the requested city, with pagination metadata.",
+        "required": [
+          "total_results",
+          "total_pages",
+          "current_page",
+          "current_page_size",
+          "codes"
+        ],
+        "properties": {
+          "total_results": {
+            "type": "integer",
+            "description": "Total number of ZIP/postal codes found, across all pages."
+          },
+          "total_pages": {
+            "type": "integer",
+            "description": "Total number of pages available."
+          },
+          "current_page": {
+            "type": "integer",
+            "description": "Current page number."
+          },
+          "current_page_size": {
+            "type": "integer",
+            "description": "Number of ZIP/postal codes in the current page."
+          },
+          "codes": {
+            "type": "array",
+            "description": "List of ZIP/postal codes for the current page.",
+            "items": {
+              "$ref": "#/components/schemas/PostalCode"
+            }
+          }
+        }
+      },
+      "PostalCode": {
+        "type": "string",
+        "description": "A single ZIP or postal code."
+      },
+      "ErrorResponse": {
+        "type": "object",
+        "description": "Standard error envelope returned by the API on failed requests.",
+        "required": ["message"],
+        "properties": {
+          "error": {
+            "type": "string",
+            "description": "Short error category or exception type."
+          },
+          "message": {
+            "type": "string",
+            "description": "Human-readable error message describing the failure."
+          },
+          "path": {
+            "type": "string",
+            "description": "API endpoint path that produced the error."
+          },
+          "status": {
+            "type": "integer",
+            "description": "HTTP status code returned with the error."
+          },
+          "timestamp": {
+            "type": "string",
+            "format": "date-time",
+            "description": "Timestamp when the error occurred (ISO 8601)."
+          }
+        }
+      }
+    }
+  },
+  "security": [
+    {
+      "ApiKeyAuthHeader": []
+    },
+    {
+      "ApiKeyAuthQuery": []
+    }
+  ]
+}

package/specs/zip-code/zip-codes-by-region.json

@@ -0,0 +1,278 @@
+{
+  "openapi": "3.1.1",
+  "info": {
+    "title": "ZIP Codes by Region API Reference",
+    "version": "1.0.0",
+    "description": "Find all ZIP and postal codes for any state, province, or region worldwide. Provide a country code and either a region name or region ISO code to retrieve all codes in that administrative division; region_code takes priority when both are supplied. Results are paginated with up to 500 codes per page, and the response includes total result count, total pages, current page, and current page size. An unrecognized region returns a 404, as does requesting a page beyond the available range.",
+    "contact": {
+      "name": "APIFreaks Support",
+      "url": "https://apifreaks.com/contact",
+      "email": "support@apifreaks.com"
+    }
+  },
+  "servers": [
+    {
+      "url": "https://api.apifreaks.com/v1.0",
+      "description": "ZIP Codes by Region API Server"
+    }
+  ],
+  "paths": {
+    "/zipcode/search/region": {
+      "get": {
+        "tags": ["ZIP Code APIs"],
+        "summary": "Search ZIP codes by region",
+        "description": "Returns every ZIP/postal code within the given region, state, or province of a country.",
+        "operationId": "searchZipByRegion",
+        "parameters": [
+          {
+            "name": "format",
+            "in": "query",
+            "required": false,
+            "schema": {
+              "type": "string",
+              "enum": ["json", "xml"],
+              "default": "json"
+            },
+            "description": "Format of the response. Possible values: json, xml."
+          },
+          {
+            "name": "country",
+            "in": "query",
+            "required": true,
+            "schema": {
+              "type": "string"
+            },
+            "description": "Country code in ISO 3166-1 alpha-2 format."
+          },
+          {
+            "name": "region",
+            "in": "query",
+            "required": false,
+            "schema": {
+              "type": "string"
+            },
+            "description": "Name of the region, state, or province associated with the country. Either region or region_code is required."
+          },
+          {
+            "name": "region_code",
+            "in": "query",
+            "required": false,
+            "schema": {
+              "type": "string"
+            },
+            "description": "ISO code of the region, state, or province associated with the country. Either region or region_code is required. region_code takes priority if both are given."
+          },
+          {
+            "name": "page",
+            "in": "query",
+            "required": false,
+            "schema": {
+              "type": "integer",
+              "default": 1,
+              "minimum": 1
+            },
+            "description": "Page number to retrieve. Each page returns up to 500 results."
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "ZIP/postal codes retrieved successfully",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ZipcodeSearchRegionResponse"
+                },
+                "examples": {
+                  "success": {
+                    "summary": "Codes for a region",
+                    "value": {
+                      "total_results": 2591,
+                      "total_pages": 6,
+                      "current_page": 1,
+                      "current_page_size": 500,
+                      "codes": [
+                        "90001",
+                        "90002",
+                        "90003",
+                        "90004",
+                        "90005"
+                      ]
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "Bad Request — Missing region/region_code, invalid country code, or invalid page number",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                },
+                "examples": {
+                  "MissingRegion": {
+                    "summary": "Neither region nor region_code was provided",
+                    "value": {
+                      "error": "Invalid Param Exception",
+                      "message": "please pass correct parameters",
+                      "path": "/v1.0/zipcode/search/region",
+                      "status": 400,
+                      "timestamp": "2026-07-27T11:23:39.623Z"
+                    }
+                  },
+                  "BadCountry": {
+                    "summary": "country is not a valid ISO 3166-1 alpha-2 code",
+                    "value": {
+                      "timestamp": "2026-07-27T11:23:46.673Z",
+                      "path": "/v1.0/zipcode/search/region",
+                      "status": 400,
+                      "error": "Invalid Country Code Provided",
+                      "message": "Only ISO 3166-1 alpha-2 codes country codes are supported."
+                    }
+                  },
+                  "BadPage": {
+                    "summary": "page is 0 or negative",
+                    "value": {
+                      "timestamp": "2026-07-27T11:23:47.192Z",
+                      "path": "/v1.0/zipcode/search/region",
+                      "status": 400,
+                      "error": "Invalid Page Number",
+                      "message": "The page number must be greater than 0."
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "404": {
+            "description": "Not Found — No codes for the region, or requested page is out of range",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                },
+                "examples": {
+                  "NotFound": {
+                    "summary": "No codes found for the given region/country",
+                    "value": {
+                      "timestamp": "2026-07-27T11:23:47.785Z",
+                      "path": "/v1.0/zipcode/search/region",
+                      "status": 404,
+                      "error": "Postal/Zip Codes Not Found",
+                      "message": "No postal/zip codes found for the provided region Nonexistentregionxyz in country US."
+                    }
+                  },
+                  "PageNotFound": {
+                    "summary": "Requested page exceeds total_pages",
+                    "value": {
+                      "timestamp": "2026-07-27T11:23:48.312Z",
+                      "path": "/v1.0/zipcode/search/region",
+                      "status": 404,
+                      "error": "Page Not Found",
+                      "message": "The requested page exceeds the available page range."
+                    }
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+  },
+  "components": {
+    "securitySchemes": {
+      "ApiKeyAuthHeader": {
+        "type": "apiKey",
+        "in": "header",
+        "name": "X-apiKey",
+        "description": "Pass your API key via the X-apiKey request header."
+      },
+      "ApiKeyAuthQuery": {
+        "type": "apiKey",
+        "in": "query",
+        "name": "apiKey",
+        "description": "Pass your API key via the apiKey query parameter."
+      }
+    },
+    "schemas": {
+      "ZipcodeSearchRegionResponse": {
+        "type": "object",
+        "description": "ZIP/postal codes for the requested region, with pagination metadata.",
+        "required": [
+          "total_results",
+          "total_pages",
+          "current_page",
+          "current_page_size",
+          "codes"
+        ],
+        "properties": {
+          "total_results": {
+            "type": "integer",
+            "description": "Total number of ZIP/postal codes found, across all pages."
+          },
+          "total_pages": {
+            "type": "integer",
+            "description": "Total number of pages available."
+          },
+          "current_page": {
+            "type": "integer",
+            "description": "Current page number."
+          },
+          "current_page_size": {
+            "type": "integer",
+            "description": "Number of ZIP/postal codes in the current page."
+          },
+          "codes": {
+            "type": "array",
+            "description": "List of ZIP/postal codes for the current page.",
+            "items": {
+              "$ref": "#/components/schemas/PostalCode"
+            }
+          }
+        }
+      },
+      "PostalCode": {
+        "type": "string",
+        "description": "A single ZIP or postal code."
+      },
+      "ErrorResponse": {
+        "type": "object",
+        "description": "Standard error envelope returned by the API on failed requests.",
+        "required": ["message"],
+        "properties": {
+          "error": {
+            "type": "string",
+            "description": "Short error category or exception type."
+          },
+          "message": {
+            "type": "string",
+            "description": "Human-readable error message describing the failure."
+          },
+          "path": {
+            "type": "string",
+            "description": "API endpoint path that produced the error."
+          },
+          "status": {
+            "type": "integer",
+            "description": "HTTP status code returned with the error."
+          },
+          "timestamp": {
+            "type": "string",
+            "format": "date-time",
+            "description": "Timestamp when the error occurred (ISO 8601)."
+          }
+        }
+      }
+    }
+  },
+  "security": [
+    {
+      "ApiKeyAuthHeader": []
+    },
+    {
+      "ApiKeyAuthQuery": []
+    }
+  ]
+}