@apifreaks/openapi-specs 0.1.0 → 0.1.2

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

@@ -0,0 +1,168 @@
+openapi: 3.1.1
+info:
+  title: Administrative Units API - Get Country Subdivisions & Admin Units
+  version: 1.0.0
+  description: Retrieve administrative units (states, provinces, governorates, districts) for any country using ISO 3166-1 alpha-2 country codes. Each result includes the unit name, admin code, and admin level type. Optionally filter results by one or more administrative levels using the `admin_level` parameter with comma-separated level names; a level name that matches nothing returns a 200 with an empty admin_units array, not an error. A valid country code is required; countries without published admin units 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: Administrative Units API Server
+paths:
+  /geo/admin-units:
+    get:
+      tags:
+        - GeoDB APIs
+      summary: Retrieve administrative units for a country with optional level filtering
+      description: Returns all administrative units (states, provinces, districts) for a country using ISO 3166-1 alpha-2 country code. Optionally filter by one or more admin levels.
+      operationId: getAdminUnits
+      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_level
+          in: query
+          required: false
+          description: Comma-separated list to filter results by one or more administrative levels (e.g., state, district). A level name that doesn't exist for the country returns a 200 with an empty admin_units array rather than an error.
+          schema:
+            type: string
+      responses:
+        '200':
+          description: Successful response with list of administrative units
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/AdminUnitsResponse'
+              examples:
+                typicalSuccess:
+                  summary: Typical successful response
+                  value:
+                    admin_units:
+                      - name: California
+                        admin_code: CA
+                        admin_level: state
+                      - name: Texas
+                        admin_code: TX
+                        admin_level: state
+                      - name: New York
+                        admin_code: NY
+                        admin_level: state
+        '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-units
+                    status: 400
+                    timestamp: '2026-07-24T10:44:10.185Z'
+                InvalidCountryCode:
+                  summary: Malformed or unrecognized country code (also returned for well-formed but non-existent codes)
+                  value:
+                    timestamp: '2026-07-24T10:44:10.711Z'
+                    path: /v1/admin-units
+                    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 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:44:11.244Z'
+                    path: /v1/admin-units
+                    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:
+    AdminUnitsResponse:
+      type: object
+      description: Response containing the administrative units for the requested country, optionally filtered by admin_level.
+      required:
+        - admin_units
+      properties:
+        admin_units:
+          type: array
+          description: An array of administrative unit objects for the specified country.
+          items:
+            $ref: '#/components/schemas/AdminUnit'
+    AdminUnit:
+      type: object
+      description: An administrative unit object.
+      required:
+        - name
+        - admin_code
+        - admin_level
+      properties:
+        name:
+          type: string
+          description: Name of the administrative unit.
+        admin_code:
+          type: string
+          description: Administrative code of the unit.
+        admin_level:
+          type: string
+          description: Level or type of the administrative unit (e.g., state, district, province).
+    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/cities.yaml

@@ -0,0 +1,209 @@
+openapi: 3.1.1
+info:
+  title: Cities API - Get City Data for Any Country
+  version: 1.0.0
+  description: 'Retrieve all cities for a given country with their latitude, longitude, administrative unit details, and ISO country code. Uses ISO 3166-1 alpha-2 country codes. Optionally filter by administrative unit code using the `admin_unit` parameter to narrow results to a specific region or province; an admin_unit code that doesn''t exist for the country returns a 400 error here (unlike the Administrative Units endpoint''s admin_level filter, which returns an empty array for an unknown level). Each city result includes name, coordinates, admin unit information (name, code, level), and the two-letter country code. There is no pagination: large countries return every city in one response. A valid country code is required.'
+  contact:
+    name: APIFreaks Support
+    url: https://apifreaks.com/contact
+    email: support@apifreaks.com
+servers:
+  - url: https://api.apifreaks.com/v1.0
+    description: Cities API Server
+paths:
+  /geo/cities:
+    get:
+      tags:
+        - GeoDB APIs
+      summary: Retrieve cities for a country with optional admin unit filtering
+      description: Returns all cities for a country, optionally filtered by administrative unit. Each city includes name, coordinates, admin unit details, and ISO country code.
+      operationId: getCities
+      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: false
+          description: Administrative unit code used to filter cities within a specific region. An admin_unit code that doesn't exist for the specified country returns a 400 error, not an empty result.
+          schema:
+            type: string
+      responses:
+        '200':
+          description: Successful response with list of cities
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/CitiesResponse'
+              examples:
+                typicalSuccess:
+                  summary: Typical successful response
+                  value:
+                    cities:
+                      - name: Aberdeen
+                        latitude: 57.14369
+                        longitude: -2.09814
+                        admin_unit:
+                          name: Aberdeen
+                          admin_code: ABE
+                          admin_level: council area
+                        iso_alpha_2: GB
+                      - name: Balmedie
+                        latitude: 57.25052
+                        longitude: -2.06163
+                        admin_unit:
+                          name: Aberdeen
+                          admin_code: ABE
+                          admin_level: council area
+                        iso_alpha_2: GB
+        '400':
+          description: Bad Request — Missing country parameter, invalid country code, or admin_unit code not found for the country
+          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/cities
+                    status: 400
+                    timestamp: '2026-07-24T10:56:41.424Z'
+                InvalidCountryCode:
+                  summary: Malformed or unrecognized country code
+                  value:
+                    timestamp: '2026-07-24T10:56:41.913Z'
+                    path: /v1/cities
+                    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:56:42.419Z'
+                    path: /v1/cities
+                    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 cities in the database (e.g. Vatican City)
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+              examples:
+                NoCities:
+                  summary: No cities for this country
+                  value:
+                    timestamp: '2026-07-24T10:56:42.941Z'
+                    path: /v1/cities
+                    status: 404
+                    error: No Cities present in country
+                    message: This country does not have any cities 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:
+    CitiesResponse:
+      type: object
+      description: Response containing every city for the requested country (optionally filtered by admin_unit), returned unpaginated in a single array.
+      required:
+        - cities
+      properties:
+        cities:
+          type: array
+          description: An array of city objects for the specified country, optionally filtered by admin unit.
+          items:
+            $ref: '#/components/schemas/CityItem'
+    CityItem:
+      type: object
+      description: A city object containing name, coordinates, admin unit, and country code.
+      required:
+        - name
+        - latitude
+        - longitude
+        - admin_unit
+        - iso_alpha_2
+      properties:
+        name:
+          type: string
+          description: The name of the city.
+        latitude:
+          type: number
+          format: float
+          description: The geographic latitude of the city in decimal degrees.
+        longitude:
+          type: number
+          format: float
+          description: The geographic longitude of the city in decimal degrees.
+        iso_alpha_2:
+          type: string
+          description: The ISO 3166-1 alpha-2 country code the city belongs to.
+        admin_unit:
+          $ref: '#/components/schemas/AdminUnit'
+    AdminUnit:
+      type: object
+      description: An object describing the administrative unit the city belongs to.
+      required:
+        - name
+        - admin_code
+        - admin_level
+      properties:
+        name:
+          type: string
+          description: The full name of the administrative unit.
+        admin_code:
+          type: string
+          description: The short code of the administrative unit.
+        admin_level:
+          type: string
+          description: The administrative level type of the unit (e.g., province, council area).
+    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/countries-details.yaml

@@ -0,0 +1,207 @@
+openapi: 3.1.1
+info:
+  title: Country Details API Reference
+  version: 1.0.0
+  description: Get comprehensive metadata for a specific country identified by its ISO 3166-1 alpha-2 code. Returns the country name, ISO codes (alpha-2, alpha-3, numeric), phone code, capital city, top-level domain, native name, region and subregion, nationality, flag emoji, and currency details (code, name, symbol). A valid two-letter country code is required. capital, region, and subregion are empty strings (not omitted) for the same handful of uninhabited/dependent territories as the Countries list endpoint — every other field, including currency and phone code, is populated for those territories.
+  contact:
+    name: APIFreaks Support
+    url: https://apifreaks.com/contact
+    email: support@apifreaks.com
+servers:
+  - url: https://api.apifreaks.com/v1.0
+    description: Country Details API Server
+paths:
+  /geo/country/details:
+    get:
+      tags:
+        - GeoDB APIs
+      summary: Retrieve comprehensive metadata for a specific country
+      description: Returns complete country details for a single country identified by its ISO 3166-1 alpha-2 code, including ISO codes, capital, currency, phone code, nationality, and flag emoji.
+      operationId: getCountryDetails
+      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 country details
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/CountryDetailsResponse'
+              examples:
+                typicalSuccess:
+                  summary: Typical successful response
+                  value:
+                    name: United States
+                    iso_alpha_2: US
+                    iso_alpha_3: USA
+                    iso_numeric: 840
+                    phone_code: 1
+                    capital: Washington
+                    top_level_domain: .us
+                    native_name: United States
+                    region: Americas
+                    subregion: Northern America
+                    nationality: American
+                    flag_emoji: 🇺🇸
+                    currency_code: USD
+                    currency_name: United States dollar
+                    currency_symbol: $
+                unassignedFields:
+                  summary: Uninhabited territory — capital, region, and subregion are empty strings; every other field is still populated
+                  value:
+                    name: Bouvet Island
+                    iso_alpha_2: BV
+                    iso_alpha_3: BVT
+                    iso_numeric: 74
+                    phone_code: 55
+                    capital: ''
+                    top_level_domain: .bv
+                    native_name: Bouvetøya
+                    region: ''
+                    subregion: ''
+                    nationality: Bouvet Island
+                    flag_emoji: 🇧🇻
+                    currency_code: NOK
+                    currency_name: Norwegian krone
+                    currency_symbol: ko
+        '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/country/details
+                    status: 400
+                    timestamp: '2026-07-24T10:54:42.188Z'
+                InvalidCountryCode:
+                  summary: Malformed or unrecognized country code
+                  value:
+                    timestamp: '2026-07-24T10:54:42.684Z'
+                    path: /v1/country/details
+                    status: 400
+                    error: Invalid Country Code provided
+                    message: Only ISO 3166-1 alpha-2 codes country codes are supported.
+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:
+    CountryDetailsResponse:
+      type: object
+      description: Comprehensive metadata for a single country resolved from an ISO 3166-1 alpha-2 code.
+      required:
+        - name
+        - iso_alpha_2
+        - iso_alpha_3
+        - iso_numeric
+        - phone_code
+        - capital
+        - top_level_domain
+        - native_name
+        - region
+        - subregion
+        - nationality
+        - flag_emoji
+        - currency_code
+        - currency_name
+        - currency_symbol
+      properties:
+        name:
+          type: string
+          description: The full English name of the country.
+        iso_alpha_2:
+          type: string
+          description: The ISO 3166-1 alpha-2 two-letter country code.
+        iso_alpha_3:
+          type: string
+          description: The ISO 3166-1 alpha-3 three-letter country code.
+        iso_numeric:
+          type: integer
+          description: The ISO 3166-1 numeric country code.
+        phone_code:
+          type: integer
+          description: The international dialing/phone code for the country.
+        capital:
+          type: string
+          description: The capital city of the country. Empty string for uninhabited/dependent territories with no capital.
+        top_level_domain:
+          type: string
+          description: The country-code top-level internet domain.
+        native_name:
+          type: string
+          description: The name of the country in its native language.
+        region:
+          type: string
+          description: The broad geographical region the country belongs to. Empty string for a small number of territories with no assigned region.
+        subregion:
+          type: string
+          description: The more specific subregion the country belongs to. Empty string for a small number of territories with no assigned subregion.
+        nationality:
+          type: string
+          description: The demonym for citizens of the country.
+        flag_emoji:
+          type: string
+          description: The emoji flag representing the country.
+        currency_code:
+          type: string
+          description: The ISO 4217 currency code used in the country.
+        currency_name:
+          type: string
+          description: The full name of the currency used in the country.
+        currency_symbol:
+          type: string
+          description: The symbol of the currency used in 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: []