@apifreaks/openapi-specs 0.1.0 → 0.1.2

package/dist/specs/geocoding/reverse-geocoding.yaml

@@ -0,0 +1,237 @@
+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/dist/specs/geodb/administrative-units-details.yaml

@@ -0,0 +1,180 @@
+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: []

package/dist/specs/geodb/administrative-units-levels.yaml

@@ -0,0 +1,140 @@
+openapi: 3.1.1
+info:
+  title: Admin Levels API Reference
+  version: 1.0.0
+  description: Retrieve the administrative level hierarchy for any country using ISO 3166-1 alpha-2 country codes. Returns the distinct administrative level types defined for that country (e.g., state, district, province, outlying area) as a flat array of strings. Use the returned level names with the Administrative Units endpoint to filter results by one or more specific levels. A valid two-letter country code is required; invalid codes return a 400 error and countries without published admin levels 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: Admin Levels API Server
+paths:
+  /geo/admin-levels:
+    get:
+      tags:
+        - GeoDB APIs
+      summary: Retrieve administrative level types for a country
+      description: Returns the distinct administrative level types (e.g., province, district, state) defined for a given country using ISO 3166-1 alpha-2 country code.
+      operationId: getAdminLevels
+      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
+      responses:
+        '200':
+          description: Successful response with list of administrative levels
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/AdminLevelsResponse'
+              examples:
+                typicalSuccess:
+                  summary: Typical successful response
+                  value:
+                    admin_levels:
+                      - outlying area
+                      - district
+                      - state
+                      - military postal region
+        '400':
+          description: Bad Request — Missing country parameter, or country is not a valid/known ISO 3166-1 alpha-2 code
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+              examples:
+                MissingCountry:
+                  summary: Missing required country parameter
+                  value:
+                    error: Invalid Param Exception
+                    message: please pass correct parameters
+                    path: /v1.0/geo/admin-levels
+                    status: 400
+                    timestamp: '2026-07-24T10:42:02.477Z'
+                InvalidCountryCode:
+                  summary: Malformed or unrecognized country code (also returned for well-formed but non-existent codes)
+                  value:
+                    timestamp: '2026-07-24T10:42:02.997Z'
+                    path: /v1/admin-levels
+                    status: 400
+                    error: Invalid Country Code provided
+                    message: Only ISO 3166-1 alpha-2 codes country codes are supported.
+        '404':
+          description: Not Found — Country is a recognized ISO 3166-1 alpha-2 code but has no published admin levels (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:42:15.470Z'
+                    path: /v1/admin-levels
+                    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:
+    AdminLevelsResponse:
+      type: object
+      description: Response containing the distinct administrative level types defined for the requested country.
+      required:
+        - admin_levels
+      properties:
+        admin_levels:
+          type: array
+          description: An array of unique administrative level types defined for the specified country. Each value represents a category of administrative division, such as state, district, or outlying area.
+          items:
+            type: string
+    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: []