{ "openapi": "3.0.3", "info": { "title": "ApogeoAPI", "version": "1.0.0", "description": "Geographic data, IP geolocation, and live exchange rates \u2014 bundled REST API.\n\n- 250+ countries\n- 5,000+ states/provinces\n- 150,000+ cities\n- 161 live currency exchange rates (refreshed every 4 hours)\n- IP geolocation\n\nGet a free API key at https://apogeoapi.com (1,000 requests / month, no credit card).\n\nNote: routes are exposed under both /v1/api/geo/... (canonical) and /v1/... (clean alias) paths. Both work identically. Most documentation references the cleaner alias paths.", "contact": { "name": "ApogeoAPI Support", "url": "https://apogeoapi.com", "email": "support@apogeoapi.com" }, "license": { "name": "Commercial", "url": "https://apogeoapi.com/terms" } }, "servers": [ { "url": "https://api.apogeoapi.com", "description": "Production" } ], "security": [ { "apiKey": [] } ], "components": { "securitySchemes": { "apiKey": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "API key from app.apogeoapi.com" } } }, "tags": [ { "name": "Public API (clean URLs)", "description": "Marketing-friendly URL aliases (/v1/countries, /v1/ip, /v1/exchange-rates, /v1/search). Recommended." }, { "name": "Geography", "description": "Canonical /v1/api/geo/... routes \u2014 same data as clean URLs." }, { "name": "IP Geolocation", "description": "IPv4 / IPv6 country and city lookup." }, { "name": "Billing", "description": "Public pricing data." } ], "paths": { "/v1/api/geo/countries": { "get": { "operationId": "GeoController_getCountries", "summary": "Get paginated country list", "description": "Returns countries with optimized field projection. Use \"fields=basic\" for faster, lighter responses.", "parameters": [ { "name": "page", "required": false, "in": "query", "description": "Page number", "schema": { "example": 1, "type": "number" } }, { "name": "limit", "required": false, "in": "query", "description": "Results per page (max: 100)", "schema": { "example": 50, "type": "number" } }, { "name": "fields", "required": false, "in": "query", "description": "Field detail level: basic (~40% faster), standard (default), full (all fields)", "schema": { "enum": [ "basic", "standard", "full" ], "type": "string" } }, { "name": "base", "required": false, "in": "query", "description": "Base currency for exchange rates (default: USD)", "schema": { "enum": [ "USD", "EUR", "GBP", "JPY", "CHF", "CAD", "AUD", "NZD", "CNY", "HKD", "SGD", "KRW", "INR", "BRL", "MXN", "ARS", "SEK", "NOK", "DKK", "PLN", "CZK", "HUF", "TRY", "ZAR", "ILS" ], "type": "string" } } ], "responses": { "200": { "description": "Countries retrieved successfully" } }, "tags": [ "Geography" ], "security": [ { "X-API-Key": [] } ] } }, "/v1/api/geo/countries/search": { "get": { "operationId": "GeoController_searchCountries", "summary": "Search countries by name", "description": "Case-insensitive partial match search with pagination and field projection. Searches in both `name` and `native` name fields.", "parameters": [ { "name": "q", "required": true, "in": "query", "description": "Search term (min 1 char). Matches country name or native name.", "schema": { "example": "argentina", "type": "string" } }, { "name": "fields", "required": false, "in": "query", "description": "Field detail level: basic (~40% faster), standard (default), full (all fields)", "schema": { "enum": [ "basic", "standard", "full" ], "type": "string" } }, { "name": "page", "required": false, "in": "query", "description": "Page number", "schema": { "example": 1, "type": "number" } }, { "name": "limit", "required": false, "in": "query", "description": "Results per page (max: 100)", "schema": { "example": 20, "type": "number" } }, { "name": "base", "required": false, "in": "query", "description": "Base currency for exchange rates (default: USD)", "schema": { "enum": [ "USD", "EUR", "GBP", "JPY", "CHF", "CAD", "AUD", "NZD", "CNY", "HKD", "SGD", "KRW", "INR", "BRL", "MXN", "ARS", "SEK", "NOK", "DKK", "PLN", "CZK", "HUF", "TRY", "ZAR", "ILS" ], "type": "string" } } ], "responses": { "200": { "description": "Search results" } }, "tags": [ "Geography" ], "security": [ { "X-API-Key": [] } ] } }, "/v1/api/geo/countries/{code}": { "get": { "operationId": "GeoController_getCountry", "summary": "Get country by ISO code", "description": "Returns full country data by ISO 3166-1 alpha-2 (2 letters) or alpha-3 (3 letters) code. Examples: `AR`, `ARG`, `US`, `USA`, `BR`, `BRA`.", "parameters": [ { "name": "code", "required": true, "in": "path", "description": "ISO2 (AR) or ISO3 (ARG) country code. Case-insensitive.", "schema": { "example": "AR", "type": "string" } }, { "name": "base", "required": false, "in": "query", "description": "Base currency for exchange rates (default: USD)", "schema": { "enum": [ "USD", "EUR", "GBP", "JPY", "CHF", "CAD", "AUD", "NZD", "CNY", "HKD", "SGD", "KRW", "INR", "BRL", "MXN", "ARS", "SEK", "NOK", "DKK", "PLN", "CZK", "HUF", "TRY", "ZAR", "ILS" ], "type": "string" } } ], "responses": { "200": { "description": "Country found" }, "404": { "description": "Country not found" } }, "tags": [ "Geography" ], "security": [ { "X-API-Key": [] } ] } }, "/v1/api/geo/countries/{code}/currency-rate": { "get": { "operationId": "GeoController_getCountryCurrencyRate", "summary": "Get live exchange rate for a country's currency", "description": "Returns the current exchange rate for the country's currency relative to a base currency (default: USD). Supports 25 base currencies including EUR, GBP, JPY, CHF, CAD, AUD, and more. Rates are updated every 4 hours from multiple providers covering 161+ currencies with automatic fallback. Lightweight endpoint \u00e2\u20ac\u201d use this when you only need the exchange rate without full country data.", "parameters": [ { "name": "code", "required": true, "in": "path", "description": "ISO2 or ISO3 country code", "schema": { "example": "AR", "type": "string" } }, { "name": "base", "required": false, "in": "query", "description": "Base currency for the exchange rate (default: USD)", "schema": { "enum": [ "USD", "EUR", "GBP", "JPY", "CHF", "CAD", "AUD", "NZD", "CNY", "HKD", "SGD", "KRW", "INR", "BRL", "MXN", "ARS", "SEK", "NOK", "DKK", "PLN", "CZK", "HUF", "TRY", "ZAR", "ILS" ], "type": "string" } } ], "responses": { "200": { "description": "Currency rate retrieved successfully", "content": { "application/json": { "schema": { "example": { "country": "Argentina", "iso2": "AR", "currency": "ARS", "currencyName": "Argentine Peso", "currencySymbol": "$", "currencyRate": { "rate": 1048.5, "base": "USD", "lastUpdated": "2026-03-11T10:00:00.000Z" } } } } } }, "400": { "description": "Unsupported base currency" }, "404": { "description": "Country not found" } }, "tags": [ "Geography", "Exchange Rates" ], "security": [ { "X-API-Key": [] } ] } }, "/v1/api/geo/countries/{code}/states": { "get": { "operationId": "GeoController_getStates", "summary": "Get states/provinces for a country", "description": "Paginated list with optimized field projection.", "parameters": [ { "name": "code", "required": true, "in": "path", "description": "ISO2 country code", "schema": { "example": "AR", "type": "string" } }, { "name": "page", "required": false, "in": "query", "schema": { "example": 1, "type": "number" } }, { "name": "limit", "required": false, "in": "query", "schema": { "example": 50, "type": "number" } }, { "name": "fields", "required": false, "in": "query", "schema": { "enum": [ "basic", "standard", "full" ], "type": "string" } } ], "responses": { "200": { "description": "States retrieved successfully" } }, "tags": [ "Geography" ], "security": [ { "X-API-Key": [] } ] } }, "/v1/api/geo/countries/{code}/states/search": { "get": { "operationId": "GeoController_searchStates", "summary": "Search states in a country", "parameters": [ { "name": "code", "required": true, "in": "path", "schema": { "example": "AR", "type": "string" } }, { "name": "q", "required": true, "in": "query", "schema": { "example": "buenos", "type": "string" } }, { "name": "fields", "required": false, "in": "query", "schema": { "enum": [ "basic", "standard", "full" ], "type": "string" } }, { "name": "page", "required": false, "in": "query", "schema": { "example": 1, "type": "number" } }, { "name": "limit", "required": false, "in": "query", "schema": { "example": 20, "type": "number" } } ], "responses": { "200": { "description": "Search results" } }, "tags": [ "Geography" ], "security": [ { "X-API-Key": [] } ] } }, "/v1/api/geo/states/{id}": { "get": { "operationId": "GeoController_getState", "summary": "Get state by ID", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "example": 123, "type": "number" } } ], "responses": { "200": { "description": "State found" }, "404": { "description": "State not found" } }, "tags": [ "Geography" ], "security": [ { "X-API-Key": [] } ] } }, "/v1/api/geo/states/{id}/cities": { "get": { "operationId": "GeoController_getCities", "summary": "Get cities in a state", "description": "Paginated list with field projection. Use \"fields=basic\" for better performance.", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "State ID", "schema": { "example": 123, "type": "number" } }, { "name": "page", "required": false, "in": "query", "schema": { "example": 1, "type": "number" } }, { "name": "limit", "required": false, "in": "query", "schema": { "example": 100, "type": "number" } }, { "name": "fields", "required": false, "in": "query", "schema": { "enum": [ "basic", "standard", "full" ], "type": "string" } } ], "responses": { "200": { "description": "Cities retrieved successfully" } }, "tags": [ "Geography" ], "security": [ { "X-API-Key": [] } ] } }, "/v1/api/geo/states/{id}/cities/search": { "get": { "operationId": "GeoController_searchCities", "summary": "Search cities in a state", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "example": 123, "type": "number" } }, { "name": "q", "required": true, "in": "query", "schema": { "example": "mar", "type": "string" } }, { "name": "fields", "required": false, "in": "query", "schema": { "enum": [ "basic", "standard", "full" ], "type": "string" } }, { "name": "page", "required": false, "in": "query", "schema": { "example": 1, "type": "number" } }, { "name": "limit", "required": false, "in": "query", "schema": { "example": 50, "type": "number" } } ], "responses": { "200": { "description": "Search results" } }, "tags": [ "Geography" ], "security": [ { "X-API-Key": [] } ] } }, "/v1/api/geo/cities/{id}": { "get": { "operationId": "GeoController_getCity", "summary": "Get city by ID", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "example": 456, "type": "number" } } ], "responses": { "200": { "description": "City found" }, "404": { "description": "City not found" } }, "tags": [ "Geography" ], "security": [ { "X-API-Key": [] } ] } }, "/v1/api/geo/countries/region/{region}": { "get": { "operationId": "GeoController_getCountriesByRegion", "summary": "Get countries by region", "description": "Returns all countries in a geographic region. There are 6 regions in the database.", "parameters": [ { "name": "region", "required": true, "in": "path", "description": "Geographic region name. Case-sensitive.", "schema": { "enum": [ "Africa", "Americas", "Asia", "Europe", "Oceania", "Polar" ], "type": "string" } } ], "responses": { "200": { "description": "Countries in the specified region" } }, "tags": [ "Geography" ], "security": [ { "X-API-Key": [] } ] } }, "/v1/api/geo/countries/subregion/{subregion}": { "get": { "operationId": "GeoController_getCountriesBySubregion", "summary": "Get countries by subregion", "description": "Returns all countries in a geographic subregion. There are 22 subregions in the database.", "parameters": [ { "name": "subregion", "required": true, "in": "path", "description": "Geographic subregion name. Case-sensitive. Common values: South America (15), Caribbean (28), Northern America (7), Central America (7), Western Europe (9), Northern Europe (16), Southern Europe (17), Eastern Europe (11), Western Asia (17), South-Eastern Asia (11), Southern Asia (9), Eastern Asia (8), Central Asia (5), Northern Africa (7), Western Africa (17), Eastern Africa (19), Middle Africa (10), Southern Africa (7), Australia and New Zealand (5), Polynesia (10), Micronesia (7), Melanesia (5)", "schema": { "enum": [ "Caribbean", "Eastern Africa", "Southern Europe", "Western Asia", "Western Africa", "Northern Europe", "South America", "South-Eastern Asia", "Eastern Europe", "Middle Africa", "Polynesia", "Southern Asia", "Western Europe", "Eastern Asia", "Southern Africa", "Micronesia", "Central America", "Northern Africa", "Northern America", "Melanesia", "Australia and New Zealand", "Central Asia" ], "type": "string" } } ], "responses": { "200": { "description": "Countries in the specified subregion" } }, "tags": [ "Geography" ], "security": [ { "X-API-Key": [] } ] } }, "/v1/api/geo/countries/phone/{phoneCode}": { "get": { "operationId": "GeoController_getCountriesByPhoneCode", "summary": "Get countries by phone code", "description": "Returns countries matching the given international dialing code. Accepts format with or without \"+\" prefix. Some codes are shared by multiple countries (e.g. +1 = US, CA, PR, etc.).", "parameters": [ { "name": "phoneCode", "required": true, "in": "path", "description": "International dialing code (without \"+\"). Examples: 1 (US/Canada), 44 (UK), 54 (Argentina), 55 (Brazil), 91 (India), 86 (China), 81 (Japan), 49 (Germany), 33 (France), 34 (Spain), 39 (Italy), 52 (Mexico), 61 (Australia)", "schema": { "example": "54", "type": "string" } } ], "responses": { "200": { "description": "Countries with the specified phone code" } }, "tags": [ "Geography" ], "security": [ { "X-API-Key": [] } ] } }, "/v1/api/geo/countries/currency/{currency}": { "get": { "operationId": "GeoController_getCountriesByCurrency", "summary": "Get countries by currency code", "description": "Returns all countries that use the given currency. Uses ISO 4217 currency codes (3 uppercase letters). Example: `USD` returns US, Puerto Rico, Ecuador, etc.", "parameters": [ { "name": "currency", "required": true, "in": "path", "description": "ISO 4217 currency code (3 uppercase letters). Common codes: USD, EUR, GBP, JPY, ARS, BRL, MXN, CNY, INR, AUD, CAD, CHF, KRW, SEK, NOK, DKK, PLN, CZK, HUF, TRY, ZAR, ILS, NZD, SGD, HKD", "schema": { "example": "USD", "type": "string" } } ], "responses": { "200": { "description": "Countries using the specified currency" } }, "tags": [ "Geography", "Exchange Rates" ], "security": [ { "X-API-Key": [] } ] } }, "/v1/api/geo/countries/{code}/timezones": { "get": { "operationId": "GeoController_getCountryTimezones", "summary": "Get timezones for a country", "description": "Returns all timezones used in the given country. Countries that span multiple time zones (e.g. US, Russia, Australia) return multiple entries.", "parameters": [ { "name": "code", "required": true, "in": "path", "description": "ISO2 or ISO3 country code", "schema": { "example": "AR", "type": "string" } } ], "responses": { "200": { "description": "Country timezones" }, "404": { "description": "Country not found" } }, "tags": [ "Geography" ], "security": [ { "X-API-Key": [] } ] } }, "/v1/api/geo/countries/{code}/translations": { "get": { "operationId": "GeoController_getCountryTranslations", "summary": "Get country name translations", "description": "Returns the country name translated in 19 languages: kr, pt-BR, pt, nl, hr, fa, de, es, fr, ja, it, cn, tr, ru, uk, pl, ca, el, hu.", "parameters": [ { "name": "code", "required": true, "in": "path", "description": "ISO2 or ISO3 country code", "schema": { "example": "AR", "type": "string" } } ], "responses": { "200": { "description": "Country name translations" }, "404": { "description": "Country not found" } }, "tags": [ "Geography" ], "security": [ { "X-API-Key": [] } ] } }, "/v1/api/geo/states/types": { "get": { "operationId": "GeoController_getStateTypes", "summary": "List all available administrative division types", "description": "Returns all distinct state/province types with the count of subdivisions for each. Use the `type` value in `GET /states/type/{type}` to filter.", "parameters": [], "responses": { "200": { "description": "List of available types with counts" } }, "tags": [ "Geography" ], "security": [ { "X-API-Key": [] } ] } }, "/v1/api/geo/states/type/{type}": { "get": { "operationId": "GeoController_getStatesByType", "summary": "Get states by administrative division type", "description": "Returns paginated states/provinces filtered by administrative division type. Use `GET /states/types` to see all available types. Common types: `province` (1159), `district` (782), `municipality` (608), `region` (515), `state` (279), `department` (222), `county` (214), `governorate` (148), `prefecture` (109), `canton` (38).", "parameters": [ { "name": "type", "required": true, "in": "path", "description": "Administrative division type. Examples: province, state, region, district, municipality, department, county, governorate, prefecture, canton, parish, commune, emirate, oblast, voivodship", "schema": { "enum": [ "province", "district", "municipality", "region", "state", "department", "county", "governorate", "prefecture", "parish", "canton", "division", "commune", "emirate", "oblast", "voivodship", "island", "territory", "borough" ], "type": "string" } }, { "name": "page", "required": false, "in": "query", "description": "Page number (default: 1)", "schema": { "example": 1, "type": "number" } }, { "name": "limit", "required": false, "in": "query", "description": "Results per page (default: 50, max: 250)", "schema": { "example": 50, "type": "number" } } ], "responses": { "200": { "description": "Paginated states of the specified type" } }, "tags": [ "Geography" ], "security": [ { "X-API-Key": [] } ] } }, "/v1/api/geo/search": { "get": { "operationId": "GeoController_globalSearch", "summary": "Global search across countries, states, and cities", "parameters": [ { "name": "q", "required": true, "in": "query", "schema": { "example": "buenos", "type": "string" } }, { "name": "limit", "required": false, "in": "query", "schema": { "example": 20, "type": "number" } } ], "responses": { "200": { "description": "Global search results" } }, "tags": [ "Geography" ], "security": [ { "X-API-Key": [] } ] } }, "/v1/countries": { "get": { "operationId": "GeoAliasesController_listCountries", "summary": "List countries (paginated)", "parameters": [ { "name": "page", "required": false, "in": "query", "schema": { "type": "number" } }, { "name": "limit", "required": false, "in": "query", "schema": { "type": "number" } }, { "name": "fields", "required": false, "in": "query", "schema": { "enum": [ "basic", "standard", "full" ], "type": "string" } }, { "name": "base", "required": false, "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "tags": [ "Public API (clean URLs)" ], "security": [ { "X-API-Key": [] } ] } }, "/v1/countries/search": { "get": { "operationId": "GeoAliasesController_searchCountries", "summary": "Search countries by name", "parameters": [ { "name": "q", "required": true, "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "tags": [ "Public API (clean URLs)" ], "security": [ { "X-API-Key": [] } ] } }, "/v1/countries/{code}": { "get": { "operationId": "GeoAliasesController_getCountry", "summary": "Get country by ISO-2 code", "parameters": [ { "name": "code", "required": true, "in": "path", "schema": { "example": "AR", "type": "string" } }, { "name": "base", "required": false, "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "tags": [ "Public API (clean URLs)" ], "security": [ { "X-API-Key": [] } ] } }, "/v1/countries/{code}/states": { "get": { "operationId": "GeoAliasesController_listStates", "summary": "List states for a country", "parameters": [ { "name": "code", "required": true, "in": "path", "schema": { "example": "AR", "type": "string" } } ], "responses": { "200": { "description": "" } }, "tags": [ "Public API (clean URLs)" ], "security": [ { "X-API-Key": [] } ] } }, "/v1/countries/{code}/states/search": { "get": { "operationId": "GeoAliasesController_searchStates", "summary": "Search states in a country", "parameters": [ { "name": "code", "required": true, "in": "path", "schema": { "example": "AR", "type": "string" } }, { "name": "q", "required": true, "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "tags": [ "Public API (clean URLs)" ], "security": [ { "X-API-Key": [] } ] } }, "/v1/countries/region/{region}": { "get": { "operationId": "GeoAliasesController_countriesByRegion", "parameters": [ { "name": "region", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "tags": [ "Public API (clean URLs)" ], "security": [ { "X-API-Key": [] } ] } }, "/v1/countries/subregion/{subregion}": { "get": { "operationId": "GeoAliasesController_countriesBySubregion", "parameters": [ { "name": "subregion", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "tags": [ "Public API (clean URLs)" ], "security": [ { "X-API-Key": [] } ] } }, "/v1/countries/phone/{phoneCode}": { "get": { "operationId": "GeoAliasesController_countriesByPhoneCode", "parameters": [ { "name": "phoneCode", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "tags": [ "Public API (clean URLs)" ], "security": [ { "X-API-Key": [] } ] } }, "/v1/countries/currency/{currency}": { "get": { "operationId": "GeoAliasesController_countriesByCurrency", "parameters": [ { "name": "currency", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "tags": [ "Public API (clean URLs)" ], "security": [ { "X-API-Key": [] } ] } }, "/v1/countries/{code}/timezones": { "get": { "operationId": "GeoAliasesController_countryTimezones", "parameters": [ { "name": "code", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "tags": [ "Public API (clean URLs)" ], "security": [ { "X-API-Key": [] } ] } }, "/v1/countries/{code}/translations": { "get": { "operationId": "GeoAliasesController_countryTranslations", "parameters": [ { "name": "code", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "tags": [ "Public API (clean URLs)" ], "security": [ { "X-API-Key": [] } ] } }, "/v1/countries/{code}/currency-rate": { "get": { "operationId": "GeoAliasesController_countryCurrencyRate", "summary": "Get live exchange rate for a country's currency", "parameters": [ { "name": "code", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "base", "required": true, "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "tags": [ "Public API (clean URLs)" ], "security": [ { "X-API-Key": [] } ] } }, "/v1/states/{id}": { "get": { "operationId": "GeoAliasesController_getState", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "number" } } ], "responses": { "200": { "description": "" } }, "tags": [ "Public API (clean URLs)" ], "security": [ { "X-API-Key": [] } ] } }, "/v1/states/{id}/cities": { "get": { "operationId": "GeoAliasesController_listCities", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "number" } }, { "name": "page", "required": true, "in": "query", "schema": { "type": "number" } }, { "name": "limit", "required": true, "in": "query", "schema": { "type": "number" } } ], "responses": { "200": { "description": "" } }, "tags": [ "Public API (clean URLs)" ], "security": [ { "X-API-Key": [] } ] } }, "/v1/states/{id}/cities/search": { "get": { "operationId": "GeoAliasesController_searchCities", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "number" } }, { "name": "q", "required": true, "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "tags": [ "Public API (clean URLs)" ], "security": [ { "X-API-Key": [] } ] } }, "/v1/states/types": { "get": { "operationId": "GeoAliasesController_stateTypes", "parameters": [], "responses": { "200": { "description": "" } }, "tags": [ "Public API (clean URLs)" ], "security": [ { "X-API-Key": [] } ] } }, "/v1/states/type/{type}": { "get": { "operationId": "GeoAliasesController_statesByType", "parameters": [ { "name": "type", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "page", "required": true, "in": "query", "schema": { "type": "number" } }, { "name": "limit", "required": true, "in": "query", "schema": { "type": "number" } } ], "responses": { "200": { "description": "" } }, "tags": [ "Public API (clean URLs)" ], "security": [ { "X-API-Key": [] } ] } }, "/v1/cities/{id}": { "get": { "operationId": "GeoAliasesController_getCity", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "number" } } ], "responses": { "200": { "description": "" } }, "tags": [ "Public API (clean URLs)" ], "security": [ { "X-API-Key": [] } ] } }, "/v1/ip": { "get": { "operationId": "GeoAliasesController_geoSelf", "summary": "Geolocate the caller's IP", "parameters": [], "responses": { "200": { "description": "" } }, "tags": [ "Public API (clean URLs)" ], "security": [ { "X-API-Key": [] } ] } }, "/v1/ip/{address}": { "get": { "operationId": "GeoAliasesController_geoIp", "summary": "Geolocate a specific IPv4/IPv6 address", "parameters": [ { "name": "address", "required": true, "in": "path", "schema": { "example": "8.8.8.8", "type": "string" } } ], "responses": { "200": { "description": "" } }, "tags": [ "Public API (clean URLs)" ], "security": [ { "X-API-Key": [] } ] } }, "/v1/exchange-rates/{currency}": { "get": { "operationId": "GeoAliasesController_exchangeRate", "summary": "Get live exchange rate for any currency", "description": "Returns the rate for the requested currency in the chosen base. Refreshed every 4 hours. Includes a \"stale\" flag if the cache is older than 6 hours.", "parameters": [ { "name": "currency", "required": true, "in": "path", "schema": { "example": "EUR", "type": "string" } }, { "name": "base", "required": false, "in": "query", "schema": { "example": "USD", "type": "string" } } ], "responses": { "200": { "description": "" } }, "tags": [ "Public API (clean URLs)" ], "security": [ { "X-API-Key": [] } ] } }, "/v1/search": { "get": { "operationId": "GeoAliasesController_globalSearch", "summary": "Global search across countries, states, and cities", "parameters": [ { "name": "q", "required": true, "in": "query", "schema": { "type": "string" } }, { "name": "limit", "required": false, "in": "query", "schema": { "example": 20, "type": "number" } } ], "responses": { "200": { "description": "" } }, "tags": [ "Public API (clean URLs)" ], "security": [ { "X-API-Key": [] } ] } }, "/v1/billing/plans": { "get": { "operationId": "PlansController_getPlans", "summary": "Obtener configuraci\u00c3\u00b3n de todos los planes", "description": "Devuelve los l\u00c3\u00admites y precios de cada tier tal como est\u00c3\u00a1n configurados en el backend. Los precios ARS se calculan al tipo de cambio vigente. Endpoint p\u00c3\u00bablico \u00e2\u20ac\u201d no requiere autenticaci\u00c3\u00b3n.", "parameters": [], "responses": { "200": { "description": "Configuraci\u00c3\u00b3n de planes" } }, "tags": [ "Plans" ] } }, "/v1/api/geo/ip": { "get": { "operationId": "IpGeoController_getMyIp", "summary": "Geolocate your own IP address", "description": "Returns geographic information (country, region, city, coordinates, timezone) for the IP address making the request. Reads from X-Forwarded-For / X-Real-IP headers when behind a proxy. Available on Starter plan and above.", "parameters": [], "responses": { "200": { "description": "Geolocation data for the caller IP", "schema": { "example": { "ip": "190.130.45.1", "countryCode": "AR", "country": "Argentina", "region": "B", "city": "Buenos Aires", "latitude": -34.5875, "longitude": -58.6725, "timezone": "America/Argentina/Buenos_Aires", "accuracyRadius": 50, "isEU": false, "isPrivate": false } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IpGeoResponseDto" } } } }, "403": { "description": "Feature requires Starter plan or above" } }, "tags": [ "IP Geolocation" ], "security": [ { "X-API-Key": [] } ] } }, "/v1/api/geo/ip/{address}": { "get": { "operationId": "IpGeoController_getIp", "summary": "Geolocate a specific IP address", "description": "Returns geographic information for the given IPv4 or IPv6 address. Private/reserved addresses (loopback, RFC1918) return isPrivate: true. Available on Starter plan and above.", "parameters": [ { "name": "address", "required": true, "in": "path", "description": "IPv4 or IPv6 address to look up", "schema": { "example": "8.8.8.8", "type": "string" } } ], "responses": { "200": { "description": "Geolocation data for the given IP", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IpGeoResponseDto" } } } }, "403": { "description": "Feature requires Starter plan or above" } }, "tags": [ "IP Geolocation" ], "security": [ { "X-API-Key": [] } ] } } } }