{ "openapi": "3.1.0", "info": { "title": "GeoAPI.info", "description": "# Comprehensive Geolocation API\n\nA powerful geolocation API service providing IP location data, country information, holidays, and more.\n\n## Features\n\n- 🌍 **Real-time IP Geolocation** - Get location data for any IP\n- πŸŽ‰ **Holiday Calendars** - 200+ countries supported\n- πŸ›οΈ **Comprehensive Country Database** - Demographics, geography, currencies\n- πŸ” **Advanced Search & Filtering** - Search by name, continent, currency\n- 🚦 **Rate Limiting** - 100 requests per minute\n- ⚑ **Global CDN** - Powered by Cloudflare's edge network\n- πŸ”’ **CORS Enabled** - Ready for web applications\n\n## Rate Limiting\n\nThis API implements rate limiting to ensure fair usage:\n- **Limit**: 100 requests per minute per IP\n- **Burst Allowance**: 10 additional requests for short spikes\n- **Headers**: Every response includes rate limit information\n\n## Methods\n\nAll GET endpoints also support **HEAD** (headers only, empty body).\n\n## Authentication\n\nNo authentication required for public endpoints. All endpoints are free to use within rate limits.\n\n## Data attribution and reuse (CC BY-SA)\n\nISO 3166-1 fields used in country payloads (`alpha3`, official English short name as `iso3166Name`, zero-padded `isoNumeric`) and **ISO 3166-2 subdivisions** from [`GET /api/country/subdivisions`](https://geoapi.info/api/country/subdivisions) are sourced from [stefangabos/world_countries](https://github.com/stefangabos/world_countries) (npm: `world_countries_lists`) under [**CC BY-SA 4.0**](https://creativecommons.org/licenses/by-sa/4.0/).\n\n**If you redistribute or publish adaptations of that material**, CC BY-SA 4.0 generally requires **attribution** and, when you share adaptations, **ShareAlike** licensing consistent with the deed. What counts as sharing or adapting depends on your use case; **read the full license**β€”and note subdivision responses include an `attribution` object as a convenience only.\n\nOther facts (e.g. population, capitals) and assets (flags) come from separate open-licensed sources summarized on the public site: **[Terms β†’ Intellectual Property and third-party data](https://www.geoapi.info/terms#third-party-data-licenses)**. GeoAPI.info does not provide legal advice.\n\n## Error Handling\n\nThe API uses standard HTTP status codes and returns detailed error messages in JSON format", "version": "1.0.2", "contact": { "name": "GeoAPI.info Support", "url": "https://www.geoapi.info" }, "license": { "name": "MIT", "url": "https://opensource.org/licenses/MIT" } }, "servers": [ { "url": "https://geoapi.info", "description": "Production server" }, { "url": "http://localhost:8787", "description": "Development server" } ], "paths": { "/": { "get": { "summary": "API Documentation", "description": "Returns comprehensive API documentation and service information", "operationId": "getApiDocs", "tags": [ "Documentation" ], "responses": { "200": { "description": "API documentation and service information", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiDocumentation" } } } } } } }, "/api/docs": { "get": { "summary": "Interactive API Documentation", "description": "Returns the same documentation as the root endpoint", "operationId": "getApiDocsAlias", "tags": [ "Documentation" ], "responses": { "200": { "description": "API documentation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiDocumentation" } } } } } } }, "/api/openapi.json": { "get": { "summary": "OpenAPI Specification", "description": "Returns the OpenAPI 3.1 specification for this API", "operationId": "getOpenAPISpec", "tags": [ "Documentation" ], "responses": { "200": { "description": "OpenAPI specification", "content": { "application/json": { "schema": { "type": "object", "description": "OpenAPI 3.1 specification" } } } } } } }, "/api/geo": { "get": { "summary": "IP Geolocation", "description": "Get comprehensive geolocation data for the requesting IP address, including country information and today's holidays", "operationId": "getGeoLocation", "tags": [ "Geolocation" ], "responses": { "200": { "description": "Geolocation data for the requesting IP", "headers": { "X-RateLimit-Limit": { "description": "Rate limit ceiling for this IP", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Number of requests remaining in current window", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "UTC timestamp when rate limit resets", "schema": { "type": "string", "format": "date-time" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeoLocationResponse" }, "examples": { "successful_response": { "summary": "Successful geolocation response", "value": { "ip": "203.0.113.1", "location": { "country": "US", "countryName": "United States", "region": "California", "city": "San Francisco", "postalCode": "94102", "timezone": "America/Los_Angeles", "coordinates": { "latitude": "37.7749", "longitude": "-122.4194" } }, "countryInfo": { "name": "United States", "capitalCity": "Washington D.C.", "currencyCode": "USD", "currencyName": "US Dollar", "callingCode": "+1", "continent": "North America", "languages": [ "en" ] }, "todaysHolidays": [ { "name": "Independence Day", "date": "2024-07-04T00:00:00.000Z", "type": "public", "substitute": false } ], "network": { "asn": 15169, "colo": "SFO" }, "timestamp": "2024-06-13T08:00:00.000Z" } } } } } }, "429": { "$ref": "#/components/responses/RateLimitExceeded" } } } }, "/api/holidays": { "get": { "summary": "Country Holidays", "description": "Get holidays for a specific country and year", "operationId": "getHolidays", "tags": [ "Holidays" ], "parameters": [ { "name": "country", "in": "query", "description": "ISO country code (2-letter)", "required": false, "schema": { "type": "string", "pattern": "^[A-Z]{2}$", "example": "US", "default": "US" } }, { "name": "year", "in": "query", "description": "Year for which to get holidays", "required": false, "schema": { "type": "integer", "minimum": 1900, "maximum": 2100, "example": 2024 } } ], "responses": { "200": { "description": "List of holidays for the specified country and year", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HolidaysResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "429": { "$ref": "#/components/responses/RateLimitExceeded" } } } }, "/api/country": { "get": { "summary": "Country Information", "description": "Get detailed information about a specific country by code or name", "operationId": "getCountry", "tags": [ "Countries" ], "parameters": [ { "name": "code", "in": "query", "description": "ISO country code (2-letter)", "required": false, "schema": { "type": "string", "pattern": "^[A-Z]{2}$", "example": "US" } }, { "name": "name", "in": "query", "description": "Country name (alternative to code)", "required": false, "schema": { "type": "string", "example": "United States" } } ], "responses": { "200": { "description": "Detailed country information", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CountryResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimitExceeded" } } } }, "/api/country/subdivisions": { "get": { "summary": "Country subdivisions (ISO 3166-2)", "description": "Principal subdivisions (states, provinces, etc.) for a country. Data from stefangabos/world_countries (CC BY-SA 4.0).", "operationId": "getCountrySubdivisions", "tags": [ "Countries" ], "parameters": [ { "name": "code", "in": "query", "description": "ISO 3166-1 alpha-2 country code", "required": false, "schema": { "type": "string", "pattern": "^[A-Z]{2}$", "example": "US" } }, { "name": "name", "in": "query", "description": "Country name (alternative to code)", "required": false, "schema": { "type": "string", "example": "United States" } } ], "responses": { "200": { "description": "Subdivision list for the country", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CountrySubdivisionsResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimitExceeded" } } } }, "/api/countries": { "get": { "summary": "List Countries", "description": "Get a paginated list of all countries with basic information", "operationId": "getCountries", "tags": [ "Countries" ], "parameters": [ { "name": "limit", "in": "query", "description": "Number of countries per page", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 250, "default": 50, "example": 20 } }, { "name": "offset", "in": "query", "description": "Starting position for pagination", "required": false, "schema": { "type": "integer", "minimum": 0, "default": 0, "example": 0 } } ], "responses": { "200": { "description": "Paginated list of countries", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CountriesListResponse" } } } }, "429": { "$ref": "#/components/responses/RateLimitExceeded" } } } }, "/api/countries/search": { "get": { "summary": "Search Countries", "description": "Search countries by name, capital, or other attributes", "operationId": "searchCountries", "tags": [ "Countries" ], "parameters": [ { "name": "q", "in": "query", "description": "Search query", "required": true, "schema": { "type": "string", "minLength": 1, "example": "island" } } ], "responses": { "200": { "description": "Search results", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CountrySearchResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "429": { "$ref": "#/components/responses/RateLimitExceeded" } } } }, "/api/countries/continent": { "get": { "summary": "Countries by Continent", "description": "Get all countries in a specific continent", "operationId": "getCountriesByContinent", "tags": [ "Countries" ], "parameters": [ { "name": "continent", "in": "query", "description": "Continent name", "required": true, "schema": { "type": "string", "enum": [ "Africa", "Asia", "Europe", "North America", "South America", "Oceania", "Antarctica" ], "example": "Europe" } } ], "responses": { "200": { "description": "Countries in the specified continent", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CountriesByContinentResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "429": { "$ref": "#/components/responses/RateLimitExceeded" } } } }, "/api/countries/currency": { "get": { "summary": "Countries by Currency", "description": "Get all countries using a specific currency", "operationId": "getCountriesByCurrency", "tags": [ "Countries" ], "parameters": [ { "name": "currency", "in": "query", "description": "Currency code (3-letter ISO code)", "required": true, "schema": { "type": "string", "pattern": "^[A-Z]{3}$", "example": "USD" } } ], "responses": { "200": { "description": "Countries using the specified currency", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CountriesByCurrencyResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "429": { "$ref": "#/components/responses/RateLimitExceeded" } } } }, "/api/countries/stats": { "get": { "summary": "Global Statistics", "description": "Get global statistics and analytics about countries", "operationId": "getCountryStats", "tags": [ "Statistics" ], "responses": { "200": { "description": "Global statistics", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GlobalStatsResponse" } } } }, "429": { "$ref": "#/components/responses/RateLimitExceeded" } } } }, "/api/countries/aggregate": { "get": { "summary": "Aggregate fields across multiple countries", "description": "Return selected numeric fields for multiple countries plus totals", "operationId": "aggregateCountries", "tags": [ "Statistics" ], "parameters": [ { "name": "codes", "in": "query", "description": "Comma-separated ISO 3166-1 alpha-2 country codes (e.g., US,CA,MX)", "required": true, "schema": { "type": "string", "example": "US,CA" } }, { "name": "fields", "in": "query", "description": "Comma-separated numeric fields to return and sum", "required": false, "schema": { "type": "string", "example": "population,surfaceArea", "description": "Allowed: population, surfaceArea, populationDensity, lifeExpectancy, coastline, elevation, avgMaleHeight" } } ], "responses": { "200": { "description": "Aggregation result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AggregatedCountriesResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimitExceeded" } } } }, "/api/country/capital": { "get": { "summary": "Get Country Capital City", "description": "Get the capital city for a specific country", "operationId": "getCountryCapital", "tags": [ "Individual Fields" ], "parameters": [ { "name": "code", "in": "query", "description": "ISO country code (2-letter)", "required": false, "schema": { "type": "string", "pattern": "^[A-Z]{2}$", "example": "US" } }, { "name": "name", "in": "query", "description": "Country name (alternative to code)", "required": false, "schema": { "type": "string", "example": "United States" } } ], "responses": { "200": { "description": "Country capital city", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CountryFieldResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimitExceeded" } } } }, "/api/country/population": { "get": { "summary": "Get Country Population", "description": "Get the population count for a specific country", "operationId": "getCountryPopulation", "tags": [ "Individual Fields" ], "parameters": [ { "name": "code", "in": "query", "description": "ISO country code (2-letter)", "required": false, "schema": { "type": "string", "pattern": "^[A-Z]{2}$", "example": "US" } }, { "name": "name", "in": "query", "description": "Country name (alternative to code)", "required": false, "schema": { "type": "string", "example": "United States" } } ], "responses": { "200": { "description": "Country population", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CountryFieldResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimitExceeded" } } } }, "/api/country/currency": { "get": { "summary": "Get Country Currency Code", "description": "Get the currency code for a specific country", "operationId": "getCountryCurrency", "tags": [ "Individual Fields" ], "parameters": [ { "name": "code", "in": "query", "description": "ISO country code (2-letter)", "required": false, "schema": { "type": "string", "pattern": "^[A-Z]{2}$", "example": "US" } }, { "name": "name", "in": "query", "description": "Country name (alternative to code)", "required": false, "schema": { "type": "string", "example": "United States" } } ], "responses": { "200": { "description": "Country currency code", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CountryFieldResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimitExceeded" } } } }, "/api/country/languages": { "get": { "summary": "Get Country Languages", "description": "Get the spoken languages for a specific country", "operationId": "getCountryLanguages", "tags": [ "Individual Fields" ], "parameters": [ { "name": "code", "in": "query", "description": "ISO country code (2-letter)", "required": false, "schema": { "type": "string", "pattern": "^[A-Z]{2}$", "example": "US" } }, { "name": "name", "in": "query", "description": "Country name (alternative to code)", "required": false, "schema": { "type": "string", "example": "United States" } } ], "responses": { "200": { "description": "Country languages", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CountryFieldResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimitExceeded" } } } }, "/api/country/continent": { "get": { "summary": "Get Country Continent", "description": "Get the continent for a specific country", "operationId": "getCountryContinent", "tags": [ "Individual Fields" ], "parameters": [ { "name": "code", "in": "query", "description": "ISO country code (2-letter)", "required": false, "schema": { "type": "string", "pattern": "^[A-Z]{2}$", "example": "US" } }, { "name": "name", "in": "query", "description": "Country name (alternative to code)", "required": false, "schema": { "type": "string", "example": "United States" } } ], "responses": { "200": { "description": "Country continent", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CountryFieldResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimitExceeded" } } } }, "/api/country/currency-name": { "get": { "summary": "Get Country Currency Name", "description": "Get the currency name for a specific country", "operationId": "getCountryCurrencyName", "tags": [ "Individual Fields" ], "parameters": [ { "$ref": "#/components/parameters/CountryCodeParam" }, { "$ref": "#/components/parameters/CountryNameParam" } ], "responses": { "200": { "description": "Country currency name", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CountryFieldResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimitExceeded" } } } }, "/api/country/calling-code": { "get": { "summary": "Get Country Calling Code", "description": "Get the international calling code for a specific country", "operationId": "getCountryCallingCode", "tags": [ "Individual Fields" ], "parameters": [ { "$ref": "#/components/parameters/CountryCodeParam" }, { "$ref": "#/components/parameters/CountryNameParam" } ], "responses": { "200": { "description": "Country calling code", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CountryFieldResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimitExceeded" } } } }, "/api/country/cities": { "get": { "summary": "Get Country Cities", "description": "Get the major cities list for a specific country", "operationId": "getCountryCities", "tags": [ "Individual Fields" ], "parameters": [ { "$ref": "#/components/parameters/CountryCodeParam" }, { "$ref": "#/components/parameters/CountryNameParam" } ], "responses": { "200": { "description": "Country major cities", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CountryFieldResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimitExceeded" } } } }, "/api/country/flags": { "get": { "summary": "Get Country Flag URLs", "description": "Get flag URLs for both square and rectangular formats", "operationId": "getCountryFlags", "tags": [ "Individual Fields" ], "parameters": [ { "$ref": "#/components/parameters/CountryCodeParam" }, { "$ref": "#/components/parameters/CountryNameParam" } ], "responses": { "200": { "description": "Country flag URLs", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CountryFieldResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimitExceeded" } } } }, "/api/country/flag-square": { "get": { "summary": "Get Square Country Flag URL", "description": "Get the square format flag URL (1:1 aspect ratio) for a specific country", "operationId": "getCountryFlagSquare", "tags": [ "Country Flags" ], "parameters": [ { "$ref": "#/components/parameters/CountryCodeParam" }, { "$ref": "#/components/parameters/CountryNameParam" } ], "responses": { "200": { "description": "Square flag URL", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CountryFlagResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimitExceeded" } } } }, "/api/country/flag-rectangular": { "get": { "summary": "Get Rectangular Country Flag URL", "description": "Get the rectangular format flag URL (4:3 aspect ratio) for a specific country", "operationId": "getCountryFlagRectangular", "tags": [ "Country Flags" ], "parameters": [ { "$ref": "#/components/parameters/CountryCodeParam" }, { "$ref": "#/components/parameters/CountryNameParam" } ], "responses": { "200": { "description": "Rectangular flag URL", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CountryFlagResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimitExceeded" } } } }, "/api/country/surface-area": { "get": { "summary": "Get Country Surface Area", "description": "Get the surface area in square kilometers for a specific country", "operationId": "getCountrySurfaceArea", "tags": [ "Individual Fields" ], "parameters": [ { "$ref": "#/components/parameters/CountryCodeParam" }, { "$ref": "#/components/parameters/CountryNameParam" } ], "responses": { "200": { "description": "Country surface area", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CountryFieldResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimitExceeded" } } } }, "/api/country/population-density": { "get": { "summary": "Get Country Population Density", "description": "Get the population density (people per square km) for a specific country", "operationId": "getCountryPopulationDensity", "tags": [ "Individual Fields" ], "parameters": [ { "$ref": "#/components/parameters/CountryCodeParam" }, { "$ref": "#/components/parameters/CountryNameParam" } ], "responses": { "200": { "description": "Country population density", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CountryFieldResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimitExceeded" } } } }, "/api/country/life-expectancy": { "get": { "summary": "Get Country Life Expectancy", "description": "Get the average life expectancy in years for a specific country", "operationId": "getCountryLifeExpectancy", "tags": [ "Individual Fields" ], "parameters": [ { "$ref": "#/components/parameters/CountryCodeParam" }, { "$ref": "#/components/parameters/CountryNameParam" } ], "responses": { "200": { "description": "Country life expectancy", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CountryFieldResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimitExceeded" } } } }, "/api/country/government": { "get": { "summary": "Get Country Government Type", "description": "Get the government type for a specific country", "operationId": "getCountryGovernment", "tags": [ "Individual Fields" ], "parameters": [ { "$ref": "#/components/parameters/CountryCodeParam" }, { "$ref": "#/components/parameters/CountryNameParam" } ], "responses": { "200": { "description": "Country government type", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CountryFieldResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimitExceeded" } } } }, "/api/country/independence-date": { "get": { "summary": "Get Country Independence Date", "description": "Get the independence date for a specific country", "operationId": "getCountryIndependenceDate", "tags": [ "Individual Fields" ], "parameters": [ { "$ref": "#/components/parameters/CountryCodeParam" }, { "$ref": "#/components/parameters/CountryNameParam" } ], "responses": { "200": { "description": "Country independence date", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CountryFieldResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimitExceeded" } } } }, "/api/country/region": { "get": { "summary": "Get Country Region", "description": "Get the region in the world for a specific country", "operationId": "getCountryRegion", "tags": [ "Individual Fields" ], "parameters": [ { "$ref": "#/components/parameters/CountryCodeParam" }, { "$ref": "#/components/parameters/CountryNameParam" } ], "responses": { "200": { "description": "Country region", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CountryFieldResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimitExceeded" } } } }, "/api/country/religion": { "get": { "summary": "Get Country Religion", "description": "Get the primary religion for a specific country", "operationId": "getCountryReligion", "tags": [ "Individual Fields" ], "parameters": [ { "$ref": "#/components/parameters/CountryCodeParam" }, { "$ref": "#/components/parameters/CountryNameParam" } ], "responses": { "200": { "description": "Country religion", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CountryFieldResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimitExceeded" } } } }, "/api/country/temperature": { "get": { "summary": "Get Country Average Temperature", "description": "Get the average temperature in Celsius for a specific country", "operationId": "getCountryTemperature", "tags": [ "Individual Fields" ], "parameters": [ { "$ref": "#/components/parameters/CountryCodeParam" }, { "$ref": "#/components/parameters/CountryNameParam" } ], "responses": { "200": { "description": "Country average temperature", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CountryFieldResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimitExceeded" } } } }, "/api/country/landlocked": { "get": { "summary": "Get Country Landlocked Status", "description": "Get whether a specific country is landlocked", "operationId": "getCountryLandlocked", "tags": [ "Individual Fields" ], "parameters": [ { "$ref": "#/components/parameters/CountryCodeParam" }, { "$ref": "#/components/parameters/CountryNameParam" } ], "responses": { "200": { "description": "Country landlocked status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CountryFieldResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimitExceeded" } } } }, "/api/country/driving-side": { "get": { "summary": "Get Country Driving Side", "description": "Get the driving side (left or right) for a specific country", "operationId": "getCountryDrivingSide", "tags": [ "Individual Fields" ], "parameters": [ { "$ref": "#/components/parameters/CountryCodeParam" }, { "$ref": "#/components/parameters/CountryNameParam" } ], "responses": { "200": { "description": "Country driving side", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CountryFieldResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimitExceeded" } } } }, "/api/country/coastline": { "get": { "summary": "Get Country Coastline Length", "description": "Get the coastline length in kilometers for a specific country", "operationId": "getCountryCoastline", "tags": [ "Individual Fields" ], "parameters": [ { "$ref": "#/components/parameters/CountryCodeParam" }, { "$ref": "#/components/parameters/CountryNameParam" } ], "responses": { "200": { "description": "Country coastline length", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CountryFieldResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimitExceeded" } } } }, "/api/country/elevation": { "get": { "summary": "Get Country Elevation", "description": "Get the average elevation in meters for a specific country", "operationId": "getCountryElevation", "tags": [ "Individual Fields" ], "parameters": [ { "$ref": "#/components/parameters/CountryCodeParam" }, { "$ref": "#/components/parameters/CountryNameParam" } ], "responses": { "200": { "description": "Country elevation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CountryFieldResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimitExceeded" } } } }, "/api/country/iso-numeric": { "get": { "summary": "Get Country ISO Numeric Code", "description": "Get the ISO 3166-1 numeric code for a specific country", "operationId": "getCountryIsoNumeric", "tags": [ "Individual Fields" ], "parameters": [ { "$ref": "#/components/parameters/CountryCodeParam" }, { "$ref": "#/components/parameters/CountryNameParam" } ], "responses": { "200": { "description": "Country ISO numeric code", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CountryFieldResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimitExceeded" } } } }, "/api/country/male-height": { "get": { "summary": "Get Country Average Male Height", "description": "Get the average male height in centimeters for a specific country", "operationId": "getCountryMaleHeight", "tags": [ "Individual Fields" ], "parameters": [ { "$ref": "#/components/parameters/CountryCodeParam" }, { "$ref": "#/components/parameters/CountryNameParam" } ], "responses": { "200": { "description": "Country average male height", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CountryFieldResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimitExceeded" } } } }, "/api/country/barcode-prefix": { "get": { "summary": "Get Country Barcode Prefix", "description": "Get the EAN/UPC barcode prefix for a specific country", "operationId": "getCountryBarcodePrefix", "tags": [ "Individual Fields" ], "parameters": [ { "$ref": "#/components/parameters/CountryCodeParam" }, { "$ref": "#/components/parameters/CountryNameParam" } ], "responses": { "200": { "description": "Country barcode prefix", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CountryFieldResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimitExceeded" } } } }, "/api/country/alphabet-letters": { "get": { "summary": "Get Country Alphabet Letters", "description": "Get the number of letters in the alphabet for a specific country", "operationId": "getCountryAlphabetLetters", "tags": [ "Individual Fields" ], "parameters": [ { "$ref": "#/components/parameters/CountryCodeParam" }, { "$ref": "#/components/parameters/CountryNameParam" } ], "responses": { "200": { "description": "Country alphabet letters count", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CountryFieldResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimitExceeded" } } } }, "/api/country/national-dish": { "get": { "summary": "Get Country National Dish", "description": "Get the national dish for a specific country", "operationId": "getCountryNationalDish", "tags": [ "Individual Fields" ], "parameters": [ { "$ref": "#/components/parameters/CountryCodeParam" }, { "$ref": "#/components/parameters/CountryNameParam" } ], "responses": { "200": { "description": "Country national dish", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CountryFieldResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimitExceeded" } } } }, "/api/country/national-symbol": { "get": { "summary": "Get Country National Symbol", "description": "Get the national symbol for a specific country", "operationId": "getCountryNationalSymbol", "tags": [ "Individual Fields" ], "parameters": [ { "$ref": "#/components/parameters/CountryCodeParam" }, { "$ref": "#/components/parameters/CountryNameParam" } ], "responses": { "200": { "description": "Country national symbol", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CountryFieldResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimitExceeded" } } } }, "/api/country/coordinates": { "get": { "summary": "Get Country Coordinates", "description": "Get the geographic coordinates (latitude, longitude) for a specific country", "operationId": "getCountryCoordinates", "tags": [ "Individual Fields" ], "parameters": [ { "$ref": "#/components/parameters/CountryCodeParam" }, { "$ref": "#/components/parameters/CountryNameParam" } ], "responses": { "200": { "description": "Country coordinates", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CountryFieldResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimitExceeded" } } } }, "/api/country/domain-tld": { "get": { "summary": "Get Country Domain TLD", "description": "Get the top-level domain (TLD) for a specific country", "operationId": "getCountryDomainTld", "tags": [ "Individual Fields" ], "parameters": [ { "$ref": "#/components/parameters/CountryCodeParam" }, { "$ref": "#/components/parameters/CountryNameParam" } ], "responses": { "200": { "description": "Country domain TLD", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CountryFieldResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimitExceeded" } } } }, "/api/health": { "get": { "summary": "Health Check", "description": "Service health check endpoint", "operationId": "getHealth", "tags": [ "Monitoring" ], "responses": { "200": { "description": "Service health status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HealthResponse" } } } } } } }, "/api/rate-limit": { "get": { "summary": "Rate Limit Information", "description": "Get current rate limiting configuration and status", "operationId": "getRateLimitInfo", "tags": [ "Monitoring" ], "responses": { "200": { "description": "Rate limiting configuration", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitInfoResponse" } } } } } } } }, "components": { "schemas": { "ApiDocumentation": { "type": "object", "description": "Complete API documentation and service information", "properties": { "service": { "type": "string", "example": "GeoAPI.info" }, "version": { "type": "string", "example": "2.0.0" }, "description": { "type": "string" }, "status": { "type": "object", "properties": { "operational": { "type": "boolean" }, "rateLimit": { "type": "object", "properties": { "requestsPerMinute": { "type": "integer" }, "burstAllowance": { "type": "integer" }, "window": { "type": "string" } } } } }, "endpoints": { "type": "object" }, "dataset": { "type": "object" }, "features": { "type": "array", "items": { "type": "string" } }, "usage": { "type": "object" }, "examples": { "type": "object" } } }, "GeoLocationResponse": { "type": "object", "description": "Comprehensive geolocation data for an IP address", "required": [ "ip", "location", "timestamp" ], "properties": { "ip": { "type": "string", "description": "The IP address that was geolocated", "example": "203.0.113.1" }, "location": { "type": "object", "description": "Location information", "properties": { "country": { "type": "string", "description": "ISO country code", "example": "US" }, "countryName": { "type": "string", "description": "Full country name", "example": "United States" }, "region": { "type": "string", "description": "State or region", "example": "California" }, "city": { "type": "string", "description": "City name", "example": "San Francisco" }, "postalCode": { "type": "string", "description": "Postal code", "example": "94102" }, "timezone": { "type": "string", "description": "Timezone identifier", "example": "America/Los_Angeles" }, "coordinates": { "type": "object", "properties": { "latitude": { "type": "string", "description": "Latitude coordinate", "example": "37.7749" }, "longitude": { "type": "string", "description": "Longitude coordinate", "example": "-122.4194" } } } } }, "countryInfo": { "type": "object", "description": "Additional country information", "nullable": true, "properties": { "name": { "type": "string", "example": "United States" }, "capital": { "type": "string", "example": "Washington D.C." }, "currency": { "type": "string", "example": "USD" }, "phone": { "type": "string", "example": "+1" }, "continent": { "type": "string", "example": "North America" }, "languages": { "type": "array", "items": { "type": "string" }, "example": [ "en" ] } } }, "todaysHolidays": { "type": "array", "description": "Holidays occurring today in the detected country", "items": { "$ref": "#/components/schemas/Holiday" } }, "network": { "type": "object", "description": "Network information", "properties": { "asn": { "type": "integer", "description": "Autonomous System Number", "example": 15169 }, "colo": { "type": "string", "description": "Cloudflare colo location", "example": "SFO" } } }, "timestamp": { "type": "string", "format": "date-time", "description": "Response timestamp", "example": "2024-06-13T08:00:00.000Z" } } }, "Holiday": { "type": "object", "description": "Information about a holiday", "required": [ "name", "date", "type" ], "properties": { "name": { "type": "string", "description": "Holiday name", "example": "Independence Day" }, "date": { "type": "string", "format": "date-time", "description": "Holiday date", "example": "2024-07-04T00:00:00.000Z" }, "type": { "type": "string", "description": "Holiday type", "enum": [ "public", "bank", "school", "optional" ], "example": "public" }, "substitute": { "type": "boolean", "description": "Whether this is a substitute holiday", "example": false } } }, "HolidaysResponse": { "type": "object", "description": "List of holidays for a country and year", "required": [ "country", "year", "holidays" ], "properties": { "country": { "type": "string", "description": "ISO country code", "example": "US" }, "year": { "type": "integer", "description": "Year", "example": 2024 }, "holidays": { "type": "array", "description": "List of holidays", "items": { "$ref": "#/components/schemas/Holiday" } } } }, "CountryInfo": { "type": "object", "description": "Comprehensive country information", "properties": { "code": { "type": "string", "description": "ISO 2-letter country code", "example": "US" }, "name": { "type": "string", "description": "Country name", "example": "United States" }, "alpha3": { "type": "string", "description": "ISO 3166-1 alpha-3 code (stefangabos/world_countries)", "example": "USA", "nullable": true }, "iso3166Name": { "type": "string", "description": "ISO 3166 official short name in English (stefangabos/world_countries)", "example": "United States of America", "nullable": true }, "subdivisionCount": { "type": "integer", "description": "Number of ISO 3166-2 subdivisions available for this country", "example": 57, "minimum": 0 }, "capitalCity": { "type": "string", "description": "Capital city", "example": "Washington D.C.", "nullable": true }, "continent": { "type": "string", "description": "Continent", "example": "North America" }, "currencyCode": { "type": "string", "description": "ISO currency code", "example": "USD" }, "currencyName": { "type": "string", "description": "Currency name", "example": "US Dollar" }, "population": { "type": "integer", "description": "Population count", "example": 331449281, "nullable": true }, "surfaceArea": { "type": "number", "description": "Surface area in square kilometers", "example": 9833517, "nullable": true }, "populationDensity": { "type": "number", "description": "Population density per square kilometer", "example": 36, "nullable": true }, "callingCode": { "type": "string", "description": "International calling code", "example": "+1" }, "domainTld": { "type": "string", "description": "Top-level domain", "example": ".us" }, "lifeExpectancy": { "type": "number", "description": "Life expectancy in years", "example": 78.9, "nullable": true }, "governmentType": { "type": "string", "description": "Government type", "example": "Federal Republic" }, "independenceDate": { "type": "string", "description": "Independence date", "example": "1776-07-04", "nullable": true }, "regionInWorld": { "type": "string", "description": "Geographic region", "example": "Northern America" }, "religion": { "type": "string", "description": "Predominant religion", "example": "Christianity", "nullable": true }, "averageTemperature": { "type": "number", "description": "Average yearly temperature in Celsius", "example": 8.5, "nullable": true }, "landlocked": { "type": "boolean", "description": "Whether the country is landlocked", "example": false }, "drivingSide": { "type": "string", "description": "Driving side", "enum": [ "left", "right" ], "example": "right" }, "coastline": { "type": "number", "description": "Coastline length in kilometers", "example": 19924, "nullable": true }, "elevation": { "type": "number", "description": "Average elevation in meters", "example": 760, "nullable": true }, "isoNumeric": { "type": "string", "description": "ISO 3166-1 numeric code (zero-padded to 3 digits when sourced from world_countries)", "example": "840", "nullable": true }, "avgMaleHeight": { "type": "number", "description": "Average male height in centimeters", "example": 175.3, "nullable": true }, "barcodePrefix": { "type": "string", "description": "Barcode prefix for products", "example": "0-13" }, "alphabetLetters": { "type": "integer", "description": "Number of letters in alphabet", "example": 26 }, "nationalDish": { "type": "string", "description": "National dish", "example": "Hamburger", "nullable": true }, "nationalSymbol": { "type": "string", "description": "National symbol", "example": "Bald Eagle", "nullable": true }, "languages": { "type": "array", "description": "Spoken languages", "items": { "type": "string" }, "example": [ "English", "Spanish" ] }, "coordinates": { "type": "object", "description": "Geographic bounding box coordinates", "nullable": true, "properties": { "north": { "type": "number", "description": "Northern latitude boundary", "example": 71.5388 }, "south": { "type": "number", "description": "Southern latitude boundary", "example": 18.7763 }, "east": { "type": "number", "description": "Eastern longitude boundary", "example": -66.8854 }, "west": { "type": "number", "description": "Western longitude boundary", "example": 172.4463 } } } } }, "CountryResponse": { "allOf": [ { "$ref": "#/components/schemas/CountryInfo" }, { "type": "object", "properties": { "upcomingHolidays": { "type": "array", "description": "Upcoming holidays in this country", "items": { "$ref": "#/components/schemas/Holiday" } } } } ] }, "CountrySubdivision": { "type": "object", "required": [ "code", "name", "type" ], "properties": { "code": { "type": "string", "description": "Full ISO 3166-2 code", "example": "US-CA" }, "name": { "type": "string", "description": "Subdivision name (often local script)", "example": "California" }, "nameEn": { "type": "string", "nullable": true, "description": "English name when available", "example": "California" }, "type": { "type": "string", "description": "Subdivision category", "example": "state" }, "parent": { "type": "string", "nullable": true, "description": "Parent subdivision code when applicable" } } }, "CountrySubdivisionsResponse": { "type": "object", "required": [ "code", "name", "total", "subdivisions", "attribution" ], "properties": { "code": { "type": "string", "example": "US" }, "name": { "type": "string", "example": "United States" }, "iso3166Name": { "type": "string", "nullable": true, "example": "United States of America" }, "total": { "type": "integer", "description": "Number of subdivisions returned", "example": 57 }, "subdivisions": { "type": "array", "items": { "$ref": "#/components/schemas/CountrySubdivision" } }, "attribution": { "type": "object", "properties": { "source": { "type": "string", "format": "uri" }, "license": { "type": "string", "example": "CC BY-SA 4.0" }, "licenseUrl": { "type": "string", "format": "uri" } } } } }, "CountriesListResponse": { "type": "object", "description": "Paginated list of countries", "required": [ "total", "limit", "offset", "countries" ], "properties": { "total": { "type": "integer", "description": "Total number of countries", "example": 245 }, "limit": { "type": "integer", "description": "Number of countries per page", "example": 50 }, "offset": { "type": "integer", "description": "Starting position", "example": 0 }, "countries": { "type": "array", "description": "List of countries", "items": { "$ref": "#/components/schemas/CountryInfo" } } } }, "CountrySearchResponse": { "type": "object", "description": "Country search results", "required": [ "query", "total", "results" ], "properties": { "query": { "type": "string", "description": "Search query", "example": "island" }, "total": { "type": "integer", "description": "Number of results", "example": 15 }, "results": { "type": "array", "description": "Search results", "items": { "allOf": [ { "$ref": "#/components/schemas/CountryInfo" }, { "type": "object", "properties": { "matchScore": { "type": "number", "description": "Relevance score", "example": 0.95 } } } ] } } } }, "CountriesByContinentResponse": { "type": "object", "description": "Countries in a specific continent", "required": [ "continent", "total", "countries" ], "properties": { "continent": { "type": "string", "description": "Continent name", "example": "Europe" }, "total": { "type": "integer", "description": "Number of countries", "example": 44 }, "countries": { "type": "array", "description": "Countries in the continent", "items": { "$ref": "#/components/schemas/CountryInfo" } } } }, "CountriesByCurrencyResponse": { "type": "object", "description": "Countries using a specific currency", "required": [ "currency", "total", "countries" ], "properties": { "currency": { "type": "string", "description": "Currency code", "example": "USD" }, "total": { "type": "integer", "description": "Number of countries", "example": 3 }, "countries": { "type": "array", "description": "Countries using the currency", "items": { "$ref": "#/components/schemas/CountryInfo" } } } }, "AggregatedCountriesResponse": { "type": "object", "description": "Selected numeric fields for multiple countries and their totals", "properties": { "query": { "type": "object", "properties": { "codes": { "type": "array", "items": { "type": "string", "example": "US" } }, "fields": { "type": "array", "items": { "type": "string", "example": "population" } } } }, "countries": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "example": "US" }, "name": { "type": "string", "example": "United States" }, "population": { "type": "number", "nullable": true }, "surfaceArea": { "type": "number", "nullable": true }, "populationDensity": { "type": "number", "nullable": true }, "lifeExpectancy": { "type": "number", "nullable": true }, "coastline": { "type": "number", "nullable": true }, "elevation": { "type": "number", "nullable": true }, "avgMaleHeight": { "type": "number", "nullable": true } } } }, "aggregates": { "type": "object", "properties": { "totals": { "type": "object", "additionalProperties": { "type": "number" }, "example": { "population": 370000000, "surfaceArea": 10000000 } }, "averages": { "type": "object", "additionalProperties": { "type": [ "number", "null" ] }, "example": { "lifeExpectancy": 80.2 } }, "weightedAverages": { "type": "object", "description": "Weighted by population (lifeExpectancy, avgMaleHeight) or area (elevation, populationDensity). populationDensity weighted value equals combinedPopulationDensity.", "additionalProperties": { "type": [ "number", "null" ] }, "example": { "lifeExpectancy": 79.9, "populationDensity": 24.5 } }, "countsByField": { "type": "object", "additionalProperties": { "type": "integer" }, "example": { "population": 2, "surfaceArea": 2, "lifeExpectancy": 2 } }, "count": { "type": "integer", "example": 2 }, "derived": { "type": "object", "properties": { "combinedPopulationDensity": { "type": [ "number", "null" ] } } } } }, "missingCodes": { "type": "array", "items": { "type": "string" } }, "timestamp": { "type": "string", "format": "date-time" } } }, "GlobalStatsResponse": { "type": "object", "description": "Global statistics and analytics", "properties": { "globalStatistics": { "type": "object", "properties": { "totalCountries": { "type": "integer", "example": 245 }, "totalPopulation": { "type": "integer", "example": 7800000000 }, "averageLifeExpectancy": { "type": "number", "example": 72.6 }, "averageGdpPerCapita": { "type": "number", "example": 11500.5 } } }, "continentDistribution": { "type": "object" }, "topCurrencies": { "type": "array", "items": { "type": "object" } }, "topLanguages": { "type": "array", "items": { "type": "object" } }, "mostPopulousCountries": { "type": "array", "items": { "$ref": "#/components/schemas/CountryInfo" } }, "largestCountries": { "type": "array", "items": { "$ref": "#/components/schemas/CountryInfo" } } } }, "HealthResponse": { "type": "object", "description": "Service health status", "required": [ "status", "timestamp" ], "properties": { "status": { "type": "string", "enum": [ "healthy", "degraded", "unhealthy" ], "example": "healthy" }, "timestamp": { "type": "string", "format": "date-time", "example": "2024-06-13T08:00:00.000Z" }, "uptime": { "type": "integer", "description": "Service uptime in milliseconds", "example": 1718266800000 }, "version": { "type": "string", "example": "2.0.0" }, "features": { "type": "object", "properties": { "rateLimiting": { "type": "string", "example": "enabled" }, "geolocation": { "type": "string", "example": "operational" }, "holidays": { "type": "string", "example": "operational" }, "countryData": { "type": "string", "example": "operational" } } }, "datasetStats": { "type": "object", "properties": { "totalCountries": { "type": "integer", "example": 245 }, "lastUpdated": { "type": "string", "format": "date-time" } } } } }, "CountryFieldResponse": { "type": "object", "description": "Response for individual country field requests", "required": [ "country", "field", "value", "dataType", "timestamp" ], "properties": { "country": { "type": "object", "description": "Basic country identification", "properties": { "code": { "type": "string", "description": "ISO 2-letter country code", "example": "US" }, "name": { "type": "string", "description": "Country name", "example": "United States" } }, "required": [ "code", "name" ] }, "field": { "type": "string", "description": "The requested field name", "example": "population" }, "value": { "description": "The field value (type varies by field)", "oneOf": [ { "type": "string", "example": "Washington D.C." }, { "type": "number", "example": 331449281 }, { "type": "boolean", "example": false }, { "type": "array", "items": { "type": "string" }, "example": [ "English", "Spanish" ] }, { "type": "object" } ] }, "dataType": { "type": "string", "description": "The data type of the value", "enum": [ "string", "number", "boolean", "array", "object" ], "example": "number" }, "timestamp": { "type": "string", "format": "date-time", "description": "Response timestamp", "example": "2024-06-13T08:00:00.000Z" } } }, "CountryFlagResponse": { "type": "object", "description": "Response for country flag endpoints", "required": [ "country", "flag", "timestamp" ], "properties": { "country": { "type": "object", "description": "Basic country identification", "properties": { "code": { "type": "string", "description": "ISO 2-letter country code", "example": "US" }, "name": { "type": "string", "description": "Country name", "example": "United States" } }, "required": [ "code", "name" ] }, "flag": { "type": "object", "description": "Flag information", "properties": { "type": { "type": "string", "description": "Flag format type", "enum": [ "square", "rectangular" ], "example": "square" }, "url": { "type": "string", "format": "uri", "description": "Direct URL to the flag image", "example": "/flags/1x1/us.svg" }, "aspectRatio": { "type": "string", "description": "Aspect ratio of the flag", "enum": [ "1:1", "4:3" ], "example": "1:1" }, "format": { "type": "string", "description": "Image format", "enum": [ "SVG" ], "example": "SVG" } }, "required": [ "type", "url", "aspectRatio", "format" ] }, "timestamp": { "type": "string", "format": "date-time", "description": "Response timestamp", "example": "2024-06-13T08:00:00.000Z" } } }, "RateLimitInfoResponse": { "type": "object", "description": "Rate limiting configuration and status", "properties": { "rateLimiting": { "type": "object", "properties": { "enabled": { "type": "boolean", "example": true }, "configuration": { "type": "object", "properties": { "requestsPerMinute": { "type": "integer", "example": 100 }, "windowSizeMs": { "type": "integer", "example": 60000 }, "burstAllowance": { "type": "integer", "example": 10 } } }, "headers": { "type": "object", "properties": { "limit": { "type": "string", "example": "X-RateLimit-Limit" }, "remaining": { "type": "string", "example": "X-RateLimit-Remaining" }, "reset": { "type": "string", "example": "X-RateLimit-Reset" } } } } }, "documentation": { "type": "object", "properties": { "description": { "type": "string" }, "editConfiguration": { "type": "string" }, "storage": { "type": "string" } } } } }, "Error": { "type": "object", "description": "Error response", "required": [ "error" ], "properties": { "error": { "type": "string", "description": "Error type", "example": "Bad Request" }, "message": { "type": "string", "description": "Human-readable error message", "example": "Invalid request parameters" }, "code": { "type": "string", "description": "Error code", "example": "INVALID_REQUEST" }, "timestamp": { "type": "string", "format": "date-time", "description": "Error timestamp" }, "requestId": { "type": "string", "description": "Unique request identifier for debugging" } } }, "RateLimitError": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "retryAfter": { "type": "integer", "description": "Seconds until rate limit resets", "example": 45 } } } ] } }, "responses": { "BadRequest": { "description": "Bad Request - Invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "Bad Request", "message": "Invalid request parameters", "code": "INVALID_REQUEST", "timestamp": "2024-06-13T08:00:00.000Z", "requestId": "123e4567-e89b-12d3-a456-426614174000" } } } }, "NotFound": { "description": "Not Found - Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "Not Found", "message": "Country not found", "code": "NOT_FOUND", "timestamp": "2024-06-13T08:00:00.000Z", "requestId": "123e4567-e89b-12d3-a456-426614174000" } } } }, "RateLimitExceeded": { "description": "Rate Limit Exceeded", "headers": { "Retry-After": { "description": "Seconds to wait before retrying", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Rate limit ceiling", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests remaining (will be 0)", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "UTC timestamp when limit resets", "schema": { "type": "string", "format": "date-time" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" }, "example": { "error": "Rate Limit Exceeded", "message": "Too many requests. Limit: 100 requests per minute", "code": "RATE_LIMITED", "retryAfter": 45, "timestamp": "2024-06-13T08:00:00.000Z", "requestId": "123e4567-e89b-12d3-a456-426614174000" } } } } }, "securitySchemes": {}, "parameters": { "CountryCodeParam": { "name": "code", "in": "query", "description": "ISO country code (2-letter)", "required": false, "schema": { "type": "string", "pattern": "^[A-Z]{2}$", "example": "US" } }, "CountryNameParam": { "name": "name", "in": "query", "description": "Country name (alternative to code)", "required": false, "schema": { "type": "string", "example": "United States" } } }, "headers": { "X-RateLimit-Limit": { "description": "The rate limit ceiling for the current user", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Number of requests remaining in the current window", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "UTC timestamp when the rate limit resets", "schema": { "type": "string", "format": "date-time" } } } }, "tags": [ { "name": "Documentation", "summary": "Docs & spec", "description": "API documentation and specifications" }, { "name": "Geolocation", "summary": "IP geo", "description": "IP geolocation services" }, { "name": "Holidays", "summary": "Holidays", "description": "Holiday information for countries" }, { "name": "Countries", "summary": "Countries", "description": "Country data and search functionality" }, { "name": "Statistics", "summary": "Stats & aggregate", "description": "Global statistics and analytics" }, { "name": "Individual Fields", "summary": "Single fields", "description": "πŸ†• Individual field endpoints for granular country data access" }, { "name": "Country Flags", "summary": "Flags", "description": "🏴 Country flag endpoints with multiple aspect ratios and high-quality SVG flags" }, { "name": "Monitoring", "summary": "Health & rate limit", "description": "Service monitoring and health checks" } ], "externalDocs": { "description": "Find more info here", "url": "https://www.geoapi.info/" }, "_cache": { "type": "docs", "timestamp": "2026-06-04T23:23:44.532Z", "maxAge": 3600, "key": "geoapi:v2:/api/openapi.json" } }