@apifreaks/openapi-specs 0.1.0 → 0.1.1

package/dist/specs/zip-code/bulk-zip-code-lookup.yaml

@@ -0,0 +1,232 @@
+openapi: 3.1.1
+info:
+  title: Bulk ZIP Code Lookup API Reference
+  version: 1.0.0
+  description: Look up multiple ZIP or postal codes in a single POST request, up to 100 codes per batch. Each matched code returns city, region, region code, locality, country code, latitude, and longitude. Accepts an optional `country` field in the request body to limit results to one country. Codes with no match are silently omitted from the `results` array instead of appearing as per-item error entries — the array can be shorter than the requested `codes` list. A malformed request body or invalid country code returns a 400; if none of the submitted codes match anything, the whole request returns a 404.
+  contact:
+    name: APIFreaks Support
+    url: https://apifreaks.com/contact
+    email: support@apifreaks.com
+servers:
+  - url: https://api.apifreaks.com/v1.0
+    description: Bulk ZIP Code Lookup API Server
+paths:
+  /zipcode/lookup:
+    post:
+      tags:
+        - ZIP Code APIs
+      summary: Look up multiple ZIP/postal codes in one request
+      operationId: bulkLookupZipCodes
+      description: Looks up up to 100 ZIP/postal codes in a single request and returns matching location data for each code that resolves.
+      parameters:
+        - name: format
+          in: query
+          required: false
+          schema:
+            type: string
+            enum:
+              - json
+              - xml
+            default: json
+          description: 'Format of the response. Possible values: json, xml.'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/BulkZipRequest'
+            examples:
+              typicalRequest:
+                summary: Typical bulk lookup request
+                value:
+                  codes:
+                    - '10001'
+                    - '90210'
+                  country: US
+      responses:
+        '200':
+          description: Successful response. `results` contains one entry per code that matched, in match order — codes with no match are omitted rather than represented as error entries, so the array can be shorter than the requested `codes` list.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ZipcodeLookupResponse'
+              examples:
+                typicalSuccess:
+                  summary: All requested codes matched
+                  value:
+                    results:
+                      - code: '10001'
+                        country_code: US
+                        region: New York
+                        region_code: NY
+                        city: New York County
+                        locality: Manhattan
+                        latitude: 40.748436
+                        longitude: -73.99402
+                      - code: '90210'
+                        country_code: US
+                        region: California
+                        region_code: CA
+                        city: Los Angeles
+                        locality: Beverly Hills (Beverly Hills)
+                        latitude: 34.10313
+                        longitude: -118.41625
+                partialMatch:
+                  summary: One of two requested codes matched — the unmatched code is simply absent
+                  value:
+                    results:
+                      - code: '10001'
+                        country_code: US
+                        region: New York
+                        region_code: NY
+                        city: New York County
+                        locality: Manhattan
+                        latitude: 40.748436
+                        longitude: -73.99402
+        '400':
+          description: Bad Request — Malformed body, invalid country code, or over the 100-code limit
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+              examples:
+                InvalidBody:
+                  summary: codes field missing or malformed
+                  value:
+                    timestamp: '2026-07-27T11:18:38.639Z'
+                    path: /v1.0/zipcode/lookup
+                    status: 400
+                    error: Request Body Invalid
+                    message: Request body is missing required fields or is not in the expected format. Please refer to the API documentation.
+                InvalidCountryCode:
+                  summary: country is not a valid ISO 3166-1 alpha-2 code
+                  value:
+                    timestamp: '2026-07-27T11:18:39.139Z'
+                    path: /v1.0/zipcode/lookup
+                    status: 400
+                    error: Invalid Country Code Provided
+                    message: Only ISO 3166-1 alpha-2 codes country codes are supported.
+                BulkLimitExceeded:
+                  summary: More than 100 codes submitted
+                  value:
+                    timestamp: '2026-07-27T11:18:48.850Z'
+                    path: /v1.0/zipcode/lookup
+                    status: 400
+                    error: Maximum Postal/Zip Code Limit Exceeded
+                    message: A maximum of 100 postal/zip codes can be processed per request.
+        '404':
+          description: Not Found — None of the submitted codes matched anything
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+              examples:
+                ZipNotFound:
+                  summary: No codes matched
+                  value:
+                    timestamp: '2026-07-27T11:18:39.650Z'
+                    path: /v1.0/zipcode/lookup
+                    status: 404
+                    error: Postal/Zip Codes Not Found
+                    message: None of the provided postal/zip codes were found 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:
+    ZipcodeLookupResponse:
+      type: object
+      description: ZIP code lookup result containing an array of matched postal codes with location details.
+      required:
+        - results
+      properties:
+        results:
+          type: array
+          description: Array of matched ZIP code results. Codes with no match are omitted, so this array can be shorter than the requested codes list.
+          items:
+            $ref: '#/components/schemas/ZipResultItem'
+    ZipResultItem:
+      type: object
+      description: A ZIP code result containing location details.
+      required:
+        - code
+        - country_code
+        - region
+        - region_code
+        - city
+        - latitude
+        - longitude
+      properties:
+        code:
+          type: string
+          description: Postal/ZIP code of the location.
+        country_code:
+          type: string
+          description: Country code in ISO 3166-1 alpha-2 format.
+        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.
+        locality:
+          type: string
+          description: Locality or neighborhood associated with the postal code. Can be an empty string when no locality-level data exists.
+        latitude:
+          type: number
+          format: float
+          description: Latitude coordinate of the postal code location.
+        longitude:
+          type: number
+          format: float
+          description: Longitude coordinate of the postal code location.
+    BulkZipRequest:
+      type: object
+      description: Request body for bulk ZIP/postal code lookup.
+      required:
+        - codes
+      properties:
+        codes:
+          type: array
+          description: Array of ZIP or postal codes to look up. Maximum 100 codes per request.
+          items:
+            type: string
+        country:
+          type: string
+          description: ISO 3166-1 alpha-2 country code to limit the search to. Applies to every code in the batch.
+    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/dist/specs/zip-code/zip-code-api.yaml

@@ -0,0 +1,216 @@
+openapi: 3.1.1
+info:
+  title: ZIP Code API - Global ZIP & Postal Code Lookup and Validation
+  version: 1.0.0
+  description: Look up and validate a single ZIP or postal code worldwide, returning every location that uses it. Returns city, region, region code, locality, country code, latitude, and longitude for each matching location. A postal code can map to multiple locations across different countries (e.g. "90210" matches places in the US, Ukraine, Kenya, Mexico, and Pakistan) unless the optional `country` parameter narrows the search to one country. Only one code is accepted per request — for multiple codes in one call, use the Bulk ZIP Code Lookup API instead. Invalid country codes return a 400, and codes with no match return a 404.
+  contact:
+    name: APIFreaks Support
+    url: https://apifreaks.com/contact
+    email: support@apifreaks.com
+servers:
+  - url: https://api.apifreaks.com/v1.0
+    description: ZIP Code Lookup API Server
+paths:
+  /zipcode/lookup:
+    get:
+      tags:
+        - ZIP Code APIs
+      summary: Look up a ZIP/postal code
+      description: Returns every location worldwide that matches the given postal/ZIP code, optionally narrowed to one country.
+      operationId: lookupZipCode
+      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: true
+          schema:
+            type: string
+          description: The postal/ZIP code to look up. Only one code is accepted per request.
+        - name: country
+          in: query
+          required: false
+          schema:
+            type: string
+          description: Country code in ISO 3166-1 alpha-2 format. Limits results to that country. If not provided, matching locations from all countries are returned.
+      responses:
+        '200':
+          description: Successful response with matching ZIP code locations
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ZipcodeLookupResponse'
+              examples:
+                success:
+                  summary: Code matched in one country
+                  value:
+                    results:
+                      - code: '90210'
+                        country_code: US
+                        region: California
+                        region_code: CA
+                        city: Los Angeles
+                        locality: Beverly Hills (Beverly Hills)
+                        latitude: 34.10313
+                        longitude: -118.41625
+                multipleCountryMatches:
+                  summary: Same code matched across multiple countries (no country filter)
+                  value:
+                    results:
+                      - code: '90210'
+                        country_code: US
+                        region: California
+                        region_code: CA
+                        city: Los Angeles
+                        locality: Beverly Hills (Beverly Hills)
+                        latitude: 34.10313
+                        longitude: -118.41625
+                      - code: '90210'
+                        country_code: UA
+                        region: Zakarpattia Oblast
+                        region_code: '21'
+                        city: Batovo Settlement Hromada
+                        locality: Svoboda
+                        latitude: 48.35717
+                        longitude: 22.367962
+                      - code: '90210'
+                        country_code: KE
+                        region: Kitui
+                        region_code: '18'
+                        city: Matinyani
+                        locality: Kalia
+                        latitude: -1.310763
+                        longitude: 37.969997
+        '400':
+          description: Bad Request — Missing code or invalid country code
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+              examples:
+                MissingCode:
+                  summary: Missing required code parameter
+                  value:
+                    error: Invalid Param Exception
+                    message: please pass correct parameters
+                    path: /v1.0/zipcode/lookup
+                    status: 400
+                    timestamp: '2026-07-27T11:17:13.351Z'
+                InvalidCountryCode:
+                  summary: country is not a valid ISO 3166-1 alpha-2 code
+                  value:
+                    timestamp: '2026-07-27T11:17:13.872Z'
+                    path: /v1.0/zipcode/lookup
+                    status: 400
+                    error: Invalid Country Code Provided
+                    message: Only ISO 3166-1 alpha-2 codes country codes are supported.
+        '404':
+          description: Not Found — No location matches the given code
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+              examples:
+                ZipNotFound:
+                  summary: Postal/ZIP code not found
+                  value:
+                    timestamp: '2026-07-27T11:17:14.474Z'
+                    path: /v1.0/zipcode/lookup
+                    status: 404
+                    error: Postal/Zip Code Not Found
+                    message: Provided postal/zip code was not found 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:
+    ZipcodeLookupResponse:
+      type: object
+      description: ZIP code lookup result containing an array of matching postal codes with location details.
+      required:
+        - results
+      properties:
+        results:
+          type: array
+          description: Array of ZIP code results matching the requested code. When multiple locations worldwide share the same postal code, each appears as a separate entry.
+          items:
+            $ref: '#/components/schemas/ZipResultItem'
+    ZipResultItem:
+      type: object
+      description: A ZIP code result containing location details.
+      required:
+        - code
+        - country_code
+        - region
+        - region_code
+        - city
+        - latitude
+        - longitude
+      properties:
+        code:
+          type: string
+          description: Postal/ZIP code of the location.
+        country_code:
+          type: string
+          description: Country code in ISO 3166-1 alpha-2 format.
+        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.
+        locality:
+          type: string
+          description: Locality or neighborhood associated with the postal code. Can be an empty string when no locality-level data exists.
+        latitude:
+          type: number
+          format: float
+          description: Latitude coordinate of the postal code location.
+        longitude:
+          type: number
+          format: float
+          description: Longitude coordinate of the postal code location.
+    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/dist/specs/zip-code/zip-code-distance-match.yaml

@@ -0,0 +1,239 @@
+openapi: 3.1.1
+info:
+  title: ZIP Code Distance Match API Reference
+  version: 1.0.0
+  description: 'Find all pairs of postal codes within a specified distance threshold from a list of up to 100 input codes. Specify a maximum distance and receive every pair of codes whose separation is at or below that value; if no pairs fall within the threshold, a 200 with an empty results array is returned rather than a 404. Supports six distance units: kilometers, miles, yards, meters, feet, and inches. A `country` code is always required. Results include each matched pair with its calculated distance.'
+  contact:
+    name: APIFreaks Support
+    url: https://apifreaks.com/contact
+    email: support@apifreaks.com
+servers:
+  - url: https://api.apifreaks.com/v1.0
+    description: ZIP Code Distance Match API Server
+paths:
+  /zipcode/distance/match:
+    post:
+      tags:
+        - ZIP Code APIs
+      summary: Get matching ZIP/postal code pairs within a distance
+      operationId: getZipcodeDistanceMatch
+      description: Returns every pair of the requested ZIP/postal codes whose distance from each other is at or below the given threshold.
+      parameters:
+        - name: format
+          in: query
+          required: false
+          schema:
+            type: string
+            enum:
+              - json
+              - xml
+            default: json
+          description: 'Format of the response. Possible values: json, xml.'
+      requestBody:
+        required: true
+        description: The list of codes, their country, and an optional distance threshold and unit.
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/DistanceMatchRequest'
+            examples:
+              typicalRequest:
+                summary: Find pairs within 5km
+                value:
+                  codes:
+                    - '90210'
+                    - '90211'
+                    - '90212'
+                    - '10001'
+                  country: US
+                  distance: 5
+      responses:
+        '200':
+          description: Successful response with matching ZIP code pairs. If none of the codes are within the distance threshold of each other, results is an empty array — this is not a 404.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ZipcodeDistanceMatchResponse'
+              examples:
+                success:
+                  summary: Pairs within threshold
+                  value:
+                    result_count: 2
+                    results:
+                      - code_1: '90211'
+                        code_2: '90212'
+                        distance: 1.958
+                      - code_1: '90210'
+                        code_2: '90212'
+                        distance: 4.704
+                noPairsWithinThreshold:
+                  summary: No pairs within the threshold
+                  value:
+                    result_count: 0
+                    results: []
+        '400':
+          description: Bad Request — Missing/invalid body, country, or unit, or over the 100-code limit
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+              examples:
+                InvalidBody:
+                  summary: codes field missing or malformed
+                  value:
+                    timestamp: '2026-07-27T11:21:58.473Z'
+                    path: /v1.0/zipcode/distance/match
+                    status: 400
+                    error: Request Body Invalid
+                    message: Request body is missing required fields or is not in the expected format. Please refer to the API documentation.
+                MissingCountry:
+                  summary: Missing required country field
+                  value:
+                    timestamp: '2026-07-27T11:21:42.483Z'
+                    path: /v1.0/zipcode/distance/match
+                    status: 400
+                    error: Country Code Missing
+                    message: Provide a valid ISO 3166-1 alpha-2 country code.
+                BadCountry:
+                  summary: country is not a valid ISO 3166-1 alpha-2 code
+                  value:
+                    timestamp: '2026-07-27T11:21:57.332Z'
+                    path: /v1.0/zipcode/distance/match
+                    status: 400
+                    error: Invalid Country Code Provided
+                    message: Only ISO 3166-1 alpha-2 codes country codes are supported.
+                InvalidUnit:
+                  summary: unit is not one of the supported symbols
+                  value:
+                    timestamp: '2026-07-27T11:21:56.749Z'
+                    path: /v1.0/zipcode/distance/match
+                    status: 400
+                    error: Invalid Unit Symbol
+                    message: The provided unit symbol is invalid. Please refer to the documentation for supported units.
+                OverLimit:
+                  summary: More than 100 codes submitted
+                  value:
+                    timestamp: '2026-07-27T11:21:57.961Z'
+                    path: /v1.0/zipcode/distance/match
+                    status: 400
+                    error: Maximum Postal/Zip Code Limit Exceeded
+                    message: A maximum of 100 postal/zip codes can be processed per request.
+        '404':
+          description: Not Found — None of the submitted codes matched anything
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+              examples:
+                NotFound:
+                  summary: No codes matched
+                  value:
+                    timestamp: '2026-07-27T11:21:59.589Z'
+                    path: /v1.0/zipcode/distance/match
+                    status: 404
+                    error: Postal/Zip Codes Not Found
+                    message: None of the provided postal/zip codes were found 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:
+    ZipcodeDistanceMatchResponse:
+      type: object
+      description: Matching ZIP/postal code pairs within the requested distance threshold.
+      required:
+        - result_count
+        - results
+      properties:
+        result_count:
+          type: integer
+          description: Number of matching ZIP/postal code pairs returned. Zero when no pairs fall within the threshold.
+        results:
+          type: array
+          description: Array of matching code pairs within the requested distance threshold.
+          items:
+            $ref: '#/components/schemas/ZipcodeDistanceMatchItem'
+    ZipcodeDistanceMatchItem:
+      type: object
+      description: A single matched pair of ZIP/postal codes with the distance between them.
+      required:
+        - code_1
+        - code_2
+        - distance
+      properties:
+        code_1:
+          type: string
+          description: First ZIP/postal code in the pair.
+        code_2:
+          type: string
+          description: Second ZIP/postal code in the pair.
+        distance:
+          type: number
+          format: float
+          description: Distance between the ZIP/postal code pair, in the unit specified by the unit field (default km).
+    DistanceMatchRequest:
+      type: object
+      description: Request body specifying the codes, country, and distance threshold to match pairs within.
+      required:
+        - codes
+        - country
+      properties:
+        codes:
+          type: array
+          description: List of ZIP or postal codes to find pairs within the specified distance. Maximum 100 codes.
+          items:
+            $ref: '#/components/schemas/DistanceMatchInputCode'
+        country:
+          type: string
+          description: Country of the codes in ISO 3166-1 alpha-2 format. Required.
+        distance:
+          type: number
+          format: float
+          description: Maximum distance threshold. All pairs within this distance are returned. If omitted, the API applies a default threshold.
+        unit:
+          type: string
+          enum:
+            - km
+            - mi
+            - yd
+            - m
+            - ft
+            - in
+          default: km
+          description: 'Distance unit. Default: km.'
+    DistanceMatchInputCode:
+      type: string
+      description: A ZIP or postal code to find distance matches for.
+    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: []