@apifreaks/openapi-specs 0.1.0

package/specs/zip-code/zip-codes-radius-search.json

@@ -0,0 +1,349 @@
+{
+  "openapi": "3.1.1",
+  "info": {
+    "title": "Find All ZIP Codes within a Radius - ZIP Code Radius Search API",
+    "version": "1.0.0",
+    "description": "Find all ZIP or postal codes within a given radius from a central ZIP code or GPS coordinates. Supports pagination with up to 500 results per page and multiple distance units (km, mi, yd, m, ft, in). The central point can be specified by ZIP code plus country, or by latitude/longitude coordinates. Returns code, region, city, district, and distance for each matching postal code within the radius, sorted nearest-first. Maximum radius is 100 km (or the equivalent in other units).",
+    "contact": {
+      "name": "APIFreaks Support",
+      "url": "https://apifreaks.com/contact",
+      "email": "support@apifreaks.com"
+    }
+  },
+  "servers": [
+    {
+      "url": "https://api.apifreaks.com/v1.0",
+      "description": "ZIP Code Radius Search API Server"
+    }
+  ],
+  "paths": {
+    "/zipcode/search/radius": {
+      "get": {
+        "tags": ["ZIP Code APIs"],
+        "summary": "Find ZIP/postal codes within a radius",
+        "description": "Returns every ZIP/postal code within the given radius of a center point, specified either by code plus country or by latitude/longitude coordinates.",
+        "operationId": "searchZipByRadius",
+        "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": "code",
+            "in": "query",
+            "required": false,
+            "schema": {
+              "type": "string"
+            },
+            "description": "Postal/ZIP code to use as the center point for the search. Requires country to be set. Alternative to lat/long."
+          },
+          {
+            "name": "lat",
+            "in": "query",
+            "required": false,
+            "schema": {
+              "type": "number",
+              "format": "float"
+            },
+            "description": "Latitude coordinate for the center point. Alternative to code/country."
+          },
+          {
+            "name": "long",
+            "in": "query",
+            "required": false,
+            "schema": {
+              "type": "number",
+              "format": "float"
+            },
+            "description": "Longitude coordinate for the center point. Alternative to code/country."
+          },
+          {
+            "name": "country",
+            "in": "query",
+            "required": false,
+            "schema": {
+              "type": "string"
+            },
+            "description": "Country code in ISO 3166-1 alpha-2 format. Required only when using the code parameter."
+          },
+          {
+            "name": "radius",
+            "in": "query",
+            "required": true,
+            "schema": {
+              "type": "number",
+              "format": "float"
+            },
+            "description": "Search radius for the query. The maximum allowed values are: 100 km, 100 mi, 109361 yd, 100000 m, 328084 ft, 3937007.75 in."
+          },
+          {
+            "name": "unit",
+            "in": "query",
+            "required": false,
+            "schema": {
+              "type": "string",
+              "default": "km",
+              "enum": ["m", "km", "mi", "ft", "yd", "in"]
+            },
+            "description": "Unit for the radius and returned distance values. Supported distance units are m, km, mi, ft, yd, in."
+          },
+          {
+            "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 found within the specified radius",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ZipcodeSearchRadiusResponse"
+                },
+                "examples": {
+                  "success": {
+                    "summary": "Codes within radius, nearest first",
+                    "value": {
+                      "total_results": 64,
+                      "total_pages": 1,
+                      "current_page": 1,
+                      "current_page_size": 64,
+                      "results": [
+                        {
+                          "code": "90077",
+                          "region": "California",
+                          "region_code": "CA",
+                          "city": "Los Angeles",
+                          "district": "Los Angeles (Los Angeles)",
+                          "distance": 3.335
+                        },
+                        {
+                          "code": "90069",
+                          "region": "California",
+                          "region_code": "CA",
+                          "city": "Los Angeles",
+                          "district": "West Hollywood (West Hollywood)",
+                          "distance": 3.403
+                        }
+                      ]
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "Bad Request — Missing/invalid radius, coordinates, or country code",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                },
+                "examples": {
+                  "MissingRadius": {
+                    "summary": "Missing required radius parameter",
+                    "value": {
+                      "error": "Invalid Param Exception",
+                      "message": "please pass correct parameters",
+                      "path": "/v1.0/zipcode/search/radius",
+                      "status": 400,
+                      "timestamp": "2026-07-27T11:19:37.382Z"
+                    }
+                  },
+                  "InvalidRadius": {
+                    "summary": "radius exceeds the maximum allowed for the given unit",
+                    "value": {
+                      "timestamp": "2026-07-27T11:19:46.342Z",
+                      "path": "/v1.0/zipcode/search/radius",
+                      "status": 400,
+                      "error": "Invalid Radius Range",
+                      "message": "The specified radius is out of the acceptable range. Please check the documentation for valid radius limits."
+                    }
+                  },
+                  "BadLat": {
+                    "summary": "lat is outside -90 to 90",
+                    "value": {
+                      "timestamp": "2026-07-27T11:19:46.876Z",
+                      "path": "/v1.0/zipcode/search/radius",
+                      "status": 400,
+                      "error": "Invalid Latitude",
+                      "message": "Latitude must be between -90 and 90."
+                    }
+                  },
+                  "BadCountry": {
+                    "summary": "country is not a valid ISO 3166-1 alpha-2 code",
+                    "value": {
+                      "timestamp": "2026-07-27T11:19:47.407Z",
+                      "path": "/v1.0/zipcode/search/radius",
+                      "status": 400,
+                      "error": "Invalid Country Code Provided",
+                      "message": "Only ISO 3166-1 alpha-2 codes country codes are supported."
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "404": {
+            "description": "Not Found — Base ZIP/postal code does not exist",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                },
+                "examples": {
+                  "BaseNotFound": {
+                    "summary": "code is not a recognized postal/ZIP code",
+                    "value": {
+                      "timestamp": "2026-07-27T11:19:47.940Z",
+                      "path": "/v1.0/zipcode/search/radius",
+                      "status": 404,
+                      "error": "Base Postal/Zip Code Not Found",
+                      "message": "The provided base postal/zip code does not exist in our database."
+                    }
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+  },
+  "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": {
+      "ZipcodeSearchRadiusResponse": {
+        "type": "object",
+        "description": "ZIP code radius search result with pagination metadata and an array of matching codes within the specified radius.",
+        "required": [
+          "total_results",
+          "total_pages",
+          "current_page",
+          "current_page_size",
+          "results"
+        ],
+        "properties": {
+          "total_results": {
+            "type": "integer",
+            "description": "Total number of ZIP/postal codes found within the radius, 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 returned on the current page (up to 500)."
+          },
+          "results": {
+            "type": "array",
+            "description": "Array of matching ZIP/postal codes for the current page, sorted nearest-first by distance.",
+            "items": {
+              "$ref": "#/components/schemas/ZipRadiusResultItem"
+            }
+          }
+        }
+      },
+      "ZipRadiusResultItem": {
+        "type": "object",
+        "description": "A ZIP code result within the search radius, including distance from the center point.",
+        "required": ["code", "region", "region_code", "city", "distance"],
+        "properties": {
+          "code": {
+            "type": "string",
+            "description": "Postal/ZIP code of the matched location."
+          },
+          "region": {
+            "type": "string",
+            "description": "Region, state, or province associated with the postal code."
+          },
+          "region_code": {
+            "type": "string",
+            "description": "Region code or abbreviation."
+          },
+          "city": {
+            "type": "string",
+            "description": "City associated with the postal code."
+          },
+          "district": {
+            "type": "string",
+            "description": "District or neighborhood associated with the postal code. Can be an empty string when no district-level data exists."
+          },
+          "distance": {
+            "type": "number",
+            "format": "float",
+            "description": "Distance from the center point to this postal code, in the unit specified by the unit parameter."
+          }
+        }
+      },
+      "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": []
+    }
+  ]
+}