@apifreaks/openapi-specs 0.1.0

package/specs/geocoding/reverse-geocoding.json

@@ -0,0 +1,326 @@
+{
+  "openapi": "3.1.1",
+  "info": {
+    "title": "Reverse Geocoding API - Convert Coordinates to a Street Address",
+    "version": "1.0.0",
+    "description": "Convert a WGS84 latitude/longitude pair into a single human-readable address or place name. Returns the nearest matching location's structured address components (street, city, state, country), a bounding box, and any points of interest, such as a shop or building, at that location. Use the `Accept-Language` header to localize the returned name and address fields to a preferred language, falling back to `en` if the language isn't supported. Both `lat` (-90 to 90) and `lon` (-180 to 180) are required; missing, non-numeric, or out-of-range values return a `400` error.",
+    "contact": {
+      "name": "APIFreaks Support",
+      "url": "https://apifreaks.com/contact",
+      "email": "support@apifreaks.com"
+    }
+  },
+  "servers": [
+    {
+      "url": "https://api.apifreaks.com/v1.0",
+      "description": "Reverse Geocoding API Server"
+    }
+  ],
+  "paths": {
+    "/geocoder/reverse": {
+      "get": {
+        "tags": ["Geocoder APIs"],
+        "summary": "Convert coordinates into a human-readable address",
+        "description": "Look up the nearest address or place name for a given latitude and longitude pair.",
+        "operationId": "reverseGeocode",
+        "parameters": [
+          {
+            "name": "lat",
+            "in": "query",
+            "required": true,
+            "description": "WGS84 latitude value, ranging from -90 to 90.",
+            "schema": {
+              "type": "number",
+              "format": "float"
+            }
+          },
+          {
+            "name": "lon",
+            "in": "query",
+            "required": true,
+            "description": "WGS84 longitude value, ranging from -180 to 180.",
+            "schema": {
+              "type": "number",
+              "format": "float"
+            }
+          },
+          {
+            "name": "Accept-Language",
+            "in": "header",
+            "required": false,
+            "description": "Preferred language order for the result name and address, as a comma-separated list of language codes or a single code. Results are returned in the first matched language, falling back to `en` if none match.",
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Successful geocoding response",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/GeocodeResponse"
+                },
+                "examples": {
+                  "typicalSuccess": {
+                    "summary": "Typical successful response",
+                    "value": {
+                      "lat": 40.7489669,
+                      "lon": -73.985399,
+                      "name": "LensCrafters",
+                      "category": "shop",
+                      "type": "optician",
+                      "poi": [
+                        {
+                          "name": "LensCrafters",
+                          "category": "shop",
+                          "type": "optician"
+                        },
+                        {
+                          "name": "7",
+                          "category": "place",
+                          "type": "house_number"
+                        }
+                      ],
+                      "street": "West 34th Street",
+                      "area": "Manhattan, New York County",
+                      "postcode": "10001",
+                      "city": "New York",
+                      "state_code": "US-NY",
+                      "state": "New York",
+                      "country_code": "US",
+                      "country": "United States",
+                      "full_address": "LensCrafters, 7, West 34th Street, Midtown South, Manhattan Community Board 5, Manhattan, New York County, New York, 10001, United States",
+                      "bounding_box": [
+                        "40.7489169",
+                        "40.7490169",
+                        "-73.9854490",
+                        "-73.9853490"
+                      ]
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "Bad Request — Invalid or missing parameters",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                },
+                "examples": {
+                  "missingParams": {
+                    "summary": "Missing required `lat` or `lon` parameter",
+                    "value": {
+                      "error": "Invalid Param Exception",
+                      "message": "please pass correct parameters",
+                      "path": "/v1.0/geocoder/reverse",
+                      "status": 400,
+                      "timestamp": "2026-07-22T14:29:45.148Z"
+                    }
+                  },
+                  "invalidLatitudeRange": {
+                    "summary": "`lat` outside the -90 to 90 range",
+                    "value": {
+                      "error": "Invalid Latitude Provided",
+                      "message": "Latitude must be between -90 and 90.",
+                      "path": "/v1.0/geocoder/reverse",
+                      "status": 400,
+                      "timestamp": "2026-07-22T14:29:45.727Z"
+                    }
+                  },
+                  "invalidLongitudeRange": {
+                    "summary": "`lon` outside the -180 to 180 range",
+                    "value": {
+                      "error": "Invalid Longitude Provided",
+                      "message": "Longitude must be between -180 and 180.",
+                      "path": "/v1.0/geocoder/reverse",
+                      "status": 400,
+                      "timestamp": "2026-07-22T14:29:46.267Z"
+                    }
+                  },
+                  "nonNumericValue": {
+                    "summary": "`lat` or `lon` is not a valid number",
+                    "value": {
+                      "error": "Invalid Parameters Provided",
+                      "message": "Please provide valid parameters.",
+                      "path": "/v1.0/geocoder/reverse",
+                      "status": 400,
+                      "timestamp": "2026-07-22T14:29:46.809Z"
+                    }
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+  },
+  "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": {
+      "ErrorResponse": {
+        "type": "object",
+        "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)."
+          }
+        }
+      },
+      "GeocodeResponse": {
+        "type": "object",
+        "description": "The nearest geocoded location to the given coordinates, with structured address components.",
+        "required": [
+          "lat",
+          "lon",
+          "country_code",
+          "country",
+          "full_address",
+          "bounding_box"
+        ],
+        "properties": {
+          "lat": {
+            "type": "number",
+            "format": "float",
+            "description": "WGS84 latitude value for the location."
+          },
+          "lon": {
+            "type": "number",
+            "format": "float",
+            "description": "WGS84 longitude value for the location."
+          },
+          "name": {
+            "type": "string",
+            "description": "Name for the primary place searched."
+          },
+          "category": {
+            "type": "string",
+            "description": "High-level category of the place, e.g. amenity, place, natural, building, highway."
+          },
+          "type": {
+            "type": "string",
+            "description": "Specific kind within the category, e.g. fast_food, city, park, residential, house_number."
+          },
+          "poi": {
+            "type": "array",
+            "description": "Points of interest at this location.",
+            "items": {
+              "$ref": "#/components/schemas/PointOfInterest"
+            }
+          },
+          "street": {
+            "type": "string",
+            "description": "Street or road name."
+          },
+          "area": {
+            "type": "string",
+            "description": "Intra-city area below city level, e.g. suburb, borough, quarter, ward, district, sector, zone, tehsil, taluka, neighbourhood."
+          },
+          "postcode": {
+            "type": "string",
+            "description": "Postal code of the area."
+          },
+          "city": {
+            "type": "string",
+            "description": "Settlement label appropriate to the country, e.g. city, town, municipality."
+          },
+          "county": {
+            "type": "string",
+            "description": "Second-tier administrative area, e.g. county, district, shire, prefecture."
+          },
+          "state_code": {
+            "type": "string",
+            "description": "Subdivision code when available, typically ISO-3166-2 (e.g. US-TX, PK-PB)."
+          },
+          "state": {
+            "type": "string",
+            "description": "First-tier administrative area; varies by country, e.g. state, region, province, division, autonomous community."
+          },
+          "country_code": {
+            "type": "string",
+            "description": "Two-letter country code in upper case, ISO-3166-1 alpha-2."
+          },
+          "country": {
+            "type": "string",
+            "description": "Country name of the searched place."
+          },
+          "full_address": {
+            "type": "string",
+            "description": "Single-line, human-readable address of the location."
+          },
+          "bounding_box": {
+            "type": "array",
+            "description": "Extent of the feature as `[lat_min, lat_max, lon_min, lon_max]` (south, north, west, east) in WGS84 decimal degrees.",
+            "items": {
+              "type": "string"
+            },
+            "minItems": 4,
+            "maxItems": 4
+          }
+        }
+      },
+      "PointOfInterest": {
+        "type": "object",
+        "description": "A point of interest located at or near a geocoded result.",
+        "properties": {
+          "name": {
+            "type": "string",
+            "description": "Name of the point of interest."
+          },
+          "category": {
+            "type": "string",
+            "description": "High-level category of the point of interest, e.g. amenity, place, natural, building, highway."
+          },
+          "type": {
+            "type": "string",
+            "description": "Specific kind within the category, e.g. fast_food, city, park, residential, house_number."
+          }
+        }
+      }
+    }
+  },
+  "security": [
+    {
+      "ApiKeyAuthHeader": []
+    },
+    {
+      "ApiKeyAuthQuery": []
+    }
+  ]
+}

package/specs/geodb/administrative-units-details.json

@@ -0,0 +1,250 @@
+{
+  "openapi": "3.1.1",
+  "info": {
+    "title": "Admin Unit Details API Reference",
+    "version": "1.0.0",
+    "description": "Get detailed information about a specific administrative unit identified by its country code and admin unit code. Returns the unit name, admin code, ISO 3166-2 code, admin level type, country ISO code, and country name. Both the `country` and `admin_unit` parameters are required; invalid or unmatched combinations return a 400 or 404 error respectively.",
+    "contact": {
+      "name": "APIFreaks Support",
+      "url": "https://apifreaks.com/contact",
+      "email": "support@apifreaks.com"
+    }
+  },
+  "servers": [
+    {
+      "url": "https://api.apifreaks.com/v1.0",
+      "description": "Admin Unit Details API Server"
+    }
+  ],
+  "paths": {
+    "/geo/admin-unit/details": {
+      "get": {
+        "tags": ["GeoDB APIs"],
+        "summary": "Retrieve detailed information about a specific administrative unit",
+        "description": "Returns comprehensive details for a single administrative unit identified by country code and admin code.",
+        "operationId": "getAdminUnitDetails",
+        "parameters": [
+          {
+            "name": "format",
+            "in": "query",
+            "required": false,
+            "description": "Format of the response. Possible values: json, xml.",
+            "schema": {
+              "type": "string",
+              "enum": ["json", "xml"],
+              "default": "json"
+            }
+          },
+          {
+            "name": "country",
+            "in": "query",
+            "required": true,
+            "description": "Country code in ISO 3166-1 alpha-2 format (e.g., US, PK).",
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "admin_unit",
+            "in": "query",
+            "required": true,
+            "description": "Admin code of the administrative unit being requested.",
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Successful response with admin unit details",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/AdminUnitDetailsResponse"
+                },
+                "examples": {
+                  "typicalSuccess": {
+                    "summary": "Unit with a real ISO 3166-2 subdivision code",
+                    "value": {
+                      "name": "California",
+                      "admin_code": "CA",
+                      "admin_iso3166_2": "US-CA",
+                      "admin_level": "state",
+                      "country_iso3166_2": "US",
+                      "country_name": "United States"
+                    }
+                  },
+                  "noIso3166_2": {
+                    "summary": "Unit with no real ISO 3166-2 code (e.g. US military postal regions) — admin_iso3166_2 is absent",
+                    "value": {
+                      "name": "Armed Forces of the Americas",
+                      "admin_code": "AA",
+                      "admin_level": "military postal region",
+                      "country_iso3166_2": "US",
+                      "country_name": "United States"
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "Bad Request — Missing country/admin_unit parameter, invalid country code, or invalid admin code",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                },
+                "examples": {
+                  "MissingParams": {
+                    "summary": "Missing required country or admin_unit parameter",
+                    "value": {
+                      "error": "Invalid Param Exception",
+                      "message": "please pass correct parameters",
+                      "path": "/v1.0/geo/admin-unit/details",
+                      "status": 400,
+                      "timestamp": "2026-07-24T10:46:22.210Z"
+                    }
+                  },
+                  "InvalidCountryCode": {
+                    "summary": "Malformed or unrecognized country code",
+                    "value": {
+                      "timestamp": "2026-07-24T10:46:23.231Z",
+                      "path": "/v1/admin-unit/details",
+                      "status": 400,
+                      "error": "Invalid Country Code provided",
+                      "message": "Only ISO 3166-1 alpha-2 codes country codes are supported."
+                    }
+                  },
+                  "InvalidAdminCode": {
+                    "summary": "admin_unit code does not exist for the given country",
+                    "value": {
+                      "timestamp": "2026-07-24T10:46:23.768Z",
+                      "path": "/v1/admin-unit/details",
+                      "status": 400,
+                      "error": "Invalid Admin Code provided",
+                      "message": "Please provide a valid admin code."
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "404": {
+            "description": "Not Found — Country is a recognized ISO 3166-1 alpha-2 code but has no published admin units (e.g. Vatican City)",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                },
+                "examples": {
+                  "NoAdminUnits": {
+                    "summary": "No admin units for this country",
+                    "value": {
+                      "timestamp": "2026-07-24T10:46:24.259Z",
+                      "path": "/v1/admin-unit/details",
+                      "status": 404,
+                      "error": "No Admin Unit present in country",
+                      "message": "This Country does not have any admin units associated with it."
+                    }
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+  },
+  "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": {
+      "AdminUnitDetailsResponse": {
+        "type": "object",
+        "description": "Detailed information for a single administrative unit resolved from a country code and admin unit code.",
+        "required": [
+          "name",
+          "admin_code",
+          "admin_level",
+          "country_iso3166_2",
+          "country_name"
+        ],
+        "properties": {
+          "name": {
+            "type": "string",
+            "description": "Name of the administrative unit."
+          },
+          "admin_code": {
+            "type": "string",
+            "description": "Administrative code of the unit."
+          },
+          "admin_iso3166_2": {
+            "type": "string",
+            "description": "The unit's full ISO 3166-2 code, formed as {country}-{admin_code} (e.g., US-CA, PK-BA, TV-FUN)."
+          },
+          "admin_level": {
+            "type": "string",
+            "description": "Level or type of the administrative unit (e.g., province, region, state)."
+          },
+          "country_iso3166_2": {
+            "type": "string",
+            "description": "Country code in ISO 3166-1 alpha-2 format."
+          },
+          "country_name": {
+            "type": "string",
+            "description": "Name of the country."
+          }
+        }
+      },
+      "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": []
+    }
+  ]
+}