{ "openapi": "3.0.7", "info": { "title": "IPGeolocation.io: Astronomy API", "version": "3.0", "description": "Retrieve astronomical information including rise and set times for the\nSun and Moon, current position, distance from Earth, and azimuth for\na specific location and date.\n\nThe Astronomy API provides accurate-enough results (within approximately\none minute) suitable for applications like sunrise/sunset timers, though\nnot intended for precision astronomical purposes.\n\nAstronomical information can be retrieved using multiple lookup inputs:\n\n- Location address (preferably city-level)\n- Geographic coordinates (latitude and longitude)\n- IPv4 or IPv6 address\n\nIf no lookup parameter is provided, the API resolves the location using\nthe public IP address of the requesting client.\n\nTwo endpoints are available:\n\n- **Single-date lookup** (`GET /v3/astronomy`) returns astronomical\n information for a specific location and date, including sunrise,\n sunset, moonrise, moonset, twilight phases, golden hour, blue hour,\n sun and moon position data, and moon phase.\n\n- **Time series lookup** (`GET /v3/astronomy/timeSeries`) returns\n astronomical information across a date range (up to 90 days) for a\n specific location.\n\n## Authentication\n\nTwo authentication methods are supported:\n\n### API Key\n\nPass your API key as the `apiKey` query parameter on every request. You can find your\nkey in the [IPGeolocation dashboard](https://app.ipgeolocation.io/). Store it in\nserver-side environment variables. Avoid exposing it in client-side JavaScript.\n\n### Request Origin (CORS)\n\nAvailable on paid plans only. Whitelist your domain in the dashboard under the\n\"API Keys\" section. Once configured, requests from that domain (and all its subdomains)\nare accepted without passing `apiKey`. Enter your root domain (e.g. `example.com`),\nnot the full URL.\n\nEach plan has a limit on the number of extra API keys and request origins:\n\n| Plan | Extra API Keys + Request Origins |\n|---|---|\n| Starter (150K requests) | 1 |\n| Core (250K requests) | 1 |\n| Plus (500K requests) | 2 |\n| Pro (1M requests) | 2 |\n| Business (2M requests) | 3 |\n| Premium (5M requests) | 3 |\n\nAdditional keys or origins can be added for $2.50 per month each.\n\n## Credit Usage\n\nCredits are charged only for successful **HTTP 200** responses. The\nexact number of credits consumed by a request is returned in the\n`X-Credits-Charged` response header.\n\n- Each successful **Astronomy lookup** consumes **1 credit** per request.\n\n## Lookup Parameter Priority\n\nIf multiple lookup parameters are provided in a request, the API resolves\nthe location using the following priority order:\n\n1. Geographic coordinates (`lat` and `long`)\n2. `location`\n3. `ip`\n\nIf none of the lookup parameters are provided, the API resolves the\nlocation using the public IP address of the requesting client.\n\n## Time Zone Behavior\n\nBy default, all astronomical event timestamps (sunrise, sunset, moonrise,\nmoonset, twilight phases, solar noon, etc.) are returned in the local\ntime of the resolved geographic location.\n\nIf the optional `time_zone` parameter is provided, all timestamps are\nconverted to the specified IANA timezone. In this case, timestamps are\nreturned as full date-time values (`yyyy-MM-dd HH:mm`) rather than\ntime-only values (`HH:mm`), and a `time_zone` field is included in\nthe `astronomy` response object.\n\nDue to timezone differences, some events may appear on a different\ncalendar date after conversion.\n", "contact": { "name": "IPGeolocation Support", "url": "https://ipgeolocation.io", "email": "support@ipgeolocation.io" }, "termsOfService": "https://ipgeolocation.io/tos.html", "license": { "name": "Proprietary", "url": "https://ipgeolocation.io/tos.html" } }, "externalDocs": { "description": "IPGeolocation Astronomy API documentation", "url": "https://ipgeolocation.io/documentation/astronomy-api.html" }, "servers": [ { "url": "https://api.ipgeolocation.io", "description": "Production" } ], "security": [ { "ApiKeyAuth": [ ] } ], "tags": [ { "name": "Astronomy", "description": "API endpoints for retrieving astronomical information for a given\nlocation, including sunrise and sunset times, moonrise and moonset\ntimes, twilight phases, golden hour and blue hour windows, solar noon,\nsun and moon position data (altitude, azimuth, distance), and moon\nphase.\n\nA time series endpoint is also available to retrieve daily astronomical\ndata across a date range of up to 90 days.\n", "externalDocs": { "description": "IPGeolocation Astronomy API documentation", "url": "https://ipgeolocation.io/documentation/astronomy-api.html" } } ], "paths": { "/v3/astronomy": { "get": { "operationId": "lookupAstronomy", "summary": "Astronomy lookup", "description": "Returns astronomical information for a specific location and date,\nincluding:\n\n- Sunrise and sunset times\n- Moonrise and moonset times\n- Morning and evening twilight phases (astronomical, nautical, civil)\n- Golden hour and blue hour windows (morning and evening)\n- Solar noon, day length, and astronomical midnight\n- Sun position: altitude, azimuth, distance from Earth\n- Moon position: altitude, azimuth, distance from Earth, parallactic angle\n- Moon phase, illumination percentage, and angular diameter\n\nThe location can be resolved using geographic coordinates (`lat` and\n`long`), a location address (`location`), or an IP address (`ip`).\n\nIf multiple lookup parameters are provided, the API resolves the\nlocation using the following priority order:\n\n1. `lat` and `long`\n2. `location`\n3. `ip`\n\nIf none of the lookup parameters are provided, the API resolves the\nlocation using the public IP address of the requesting client.\n\nBy default, results are calculated for the current date. Pass the\n`date` parameter to retrieve data for a specific date.\n\nEach successful lookup consumes **1 credit**.\n", "tags": [ "Astronomy" ], "parameters": [ { "$ref": "#/components/parameters/Lat" }, { "$ref": "#/components/parameters/Long" }, { "$ref": "#/components/parameters/Location" }, { "$ref": "#/components/parameters/Ip" }, { "$ref": "#/components/parameters/Date" }, { "$ref": "#/components/parameters/Elevation" }, { "$ref": "#/components/parameters/TimeZone" }, { "$ref": "#/components/parameters/Lang" } ], "responses": { "200": { "description": "Successful response", "headers": { "X-Credits-Charged": { "description": "Number of API credits consumed by this request.", "schema": { "type": "number", "example": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AstronomyLookupResponse" }, "example": { "location": { "latitude": "40.76473", "longitude": "-74.00084", "country_name": "United States", "state_prov": "New York", "city": "New York", "locality": "Midtown West", "elevation": "9" }, "astronomy": { "date": "2026-03-18", "current_time": "10:15:00.000", "mid_night": "00:06", "night_end": "04:49", "morning": { "astronomical_twilight_begin": "04:49", "astronomical_twilight_end": "05:21", "nautical_twilight_begin": "05:21", "nautical_twilight_end": "05:53", "civil_twilight_begin": "05:53", "civil_twilight_end": "06:20", "blue_hour_begin": "05:42", "blue_hour_end": "06:03", "golden_hour_begin": "06:03", "golden_hour_end": "06:57" }, "sunrise": "06:20", "sunset": "19:00", "evening": { "golden_hour_begin": "18:23", "golden_hour_end": "19:16", "blue_hour_begin": "19:16", "blue_hour_end": "19:38", "civil_twilight_begin": "19:00", "civil_twilight_end": "19:27", "nautical_twilight_begin": "19:27", "nautical_twilight_end": "19:59", "astronomical_twilight_begin": "19:59", "astronomical_twilight_end": "20:31" }, "night_begin": "20:31", "sun_status": "-", "solar_noon": "12:40", "day_length": "12:40", "sun_altitude": 42.5, "sun_distance": 148900000.0, "sun_azimuth": 150.3, "moon_phase": "WAXING_CRESCENT", "moonrise": "08:45", "moonset": "22:10", "moon_status": "-", "moon_altitude": 15.2, "moon_distance": 384400.0, "moon_azimuth": 220.5, "moon_parallactic_angle": 30.1, "moon_illumination_percentage": "25.40", "moon_angle": 0.52 } } }, "application/xml": { "schema": { "$ref": "#/components/schemas/AstronomyLookupResponse" }, "example": "\n \n 40.76473\n -74.00084\n United States\n New York\n New York\n Midtown West\n 9\n \n \n 2026-03-18\n 15:54:15.261\n 01:03\n 05:31\n \n 05:31\n 06:03\n 06:03\n 06:35\n 06:35\n 07:02\n 06:24\n 06:46\n 06:46\n 07:38\n \n 07:02\n 19:06\n \n 18:30\n 19:22\n 19:22\n 19:44\n 19:06\n 19:33\n 19:33\n 20:05\n 20:05\n 20:38\n \n 20:38\n -\n 13:04\n 12:04\n 33.35169743090959\n 148782269.19009596\n 234.07341944671086\n NEW_MOON\n 06:44\n 18:57\n -\n 31.430127664137917\n 374392.1525559059\n 237.27212480757834\n 39.582319837764366\n -0.07\n 357.01360045404493\n \n\n" } } }, "400": { "description": "Bad Request – Possible reasons include:\n - If the provided IPv4 or IPv6 address is invalid.\n - If special character(s) `( ) [ ] { } | ^ \\`` is passed in the\n API URL either as a parameter or its value, especially in the\n case of an API key.\n - If the provided `date` is not in the format `yyyy-MM-dd`.\n - If an invalid or unsupported `lang` parameter is provided.\n - If the provided values for `lat` and `long` are not numbers,\n or fall outside the acceptable ranges. Valid latitude range is\n **-90 to 90**; valid longitude range is **-180 to 180**.\n - If the provided `elevation` value exceeds the maximum allowed\n value of **10,000 meters**.\n - If the provided `time_zone` is invalid or unrecognized.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "invalidIp": { "summary": "Invalid IPv4 or IPv6 address", "value": { "message": "Provided name, service or IP address '999.999.999.999' is not valid." } }, "specialCharacters": { "summary": "Invalid characters in request", "value": { "message": "Invalid character found in the request target." } }, "invalidDate": { "summary": "Invalid date format", "value": { "message": "You must provide date in the 'yyyy-MM-dd' format" } }, "invalidCoordinates": { "summary": "Coordinates out of range", "value": { "message": "Longitude must be between -180 and 180 or latitude must be between -90 and 90." } }, "invalidElevation": { "summary": "Elevation exceeds maximum", "value": { "message": "Elevation cannot be greater than 10000 meters." } }, "invalidTimezone": { "summary": "Invalid timezone identifier", "value": { "message": "Check whether your input values are correct; time_zone_name = Europe/InvalidCity" } }, "invalidLang": { "summary": "Unsupported language parameter", "value": { "message": "This 'xx' lang is not valid. Please use 'en' as the default language." } } } } } }, "401": { "description": "Unauthorized – Possible reasons include:\n - Missing or invalid API key.\n - If your account has been disabled or locked by the admin due\n to abuse or illegal activity.\n - When the request is made using an API key for a database\n subscription.\n - When the request is made on a paused subscription.\n - If you are making API requests after your subscription trial\n has expired.\n - If your active-until date has passed and you need to renew\n or upgrade your subscription.\n - A language other than English is specified in the `lang`\n parameter while using a Free/Developer plan API key.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "missingApiKey": { "summary": "Missing API key", "value": { "message": "Please provide an API key (as 'apiKey=YOUR_API_KEY' URL parameter) to use IPGeolocation API. To get your free API Key, sign up at https://app.ipgeolocation.io/login" } }, "invalidApiKey": { "summary": "Invalid API key", "value": { "message": "Provided API key is not valid. Contact technical support for assistance at support@ipgeolocation.io" } }, "lockedAccount": { "summary": "Account locked", "value": { "message": "Your account has been locked to use IPGeolocation API. Contact technical support for assistance at support@ipgeolocation.io" } }, "databaseSubscription": { "summary": "Database subscription key used", "value": { "message": "You cannot query IPGeolocation API on a database plan subscription." } }, "pausedSubscription": { "summary": "Subscription paused", "value": { "message": "Your subscription has been paused. Please resume your subscription to use IPGeolocation API." } }, "expiredSubscription": { "summary": "Subscription expired", "value": { "message": "Your subscription has expired at DATE. Please subscribe to a paid plan to continue using IPGeolocation API without interruption or contact technical support for assistance at support@ipgeolocation.io" } }, "freePlanLang": { "summary": "Non-English language on Free plan", "value": { "message": "This 'de' lang is not supported for your current subscription. Please use 'en' as the default language or upgrade your subscription to use this feature." } } } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "405": { "$ref": "#/components/responses/MethodNotAllowed" }, "423": { "$ref": "#/components/responses/Locked" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "499": { "$ref": "#/components/responses/ClientClosedRequest" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "502": { "$ref": "#/components/responses/BadGateway" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" }, "504": { "$ref": "#/components/responses/GatewayTimeout" }, "505": { "$ref": "#/components/responses/HttpVersionNotSupported" } } } }, "/v3/astronomy/timeSeries": { "get": { "operationId": "lookupAstronomyTimeSeries", "summary": "Astronomy time series lookup", "description": "Returns daily astronomical information for a specific location across\na date range.\n\nThe response contains an array of daily astronomy records, each\nincluding sunrise, sunset, moonrise, moonset, twilight phases,\nsolar noon, day length, and moon phase. Real-time positional data\n(altitude, azimuth, distance) is not included in time series\nresponses.\n\nThe location can be resolved using geographic coordinates (`lat` and\n`long`), a location address (`location`), or an IP address (`ip`).\n\n**Date range constraints:**\n- Both `dateStart` and `dateEnd` are required.\n- The maximum allowed span between `dateStart` and `dateEnd` is\n **90 days**.\n- Both past and future dates are supported within the 90-day window.\n\nEach successful lookup consumes **1 credit** per request.\n", "tags": [ "Astronomy" ], "parameters": [ { "$ref": "#/components/parameters/Lat" }, { "$ref": "#/components/parameters/Long" }, { "$ref": "#/components/parameters/Location" }, { "$ref": "#/components/parameters/Ip" }, { "$ref": "#/components/parameters/DateStart" }, { "$ref": "#/components/parameters/DateEnd" }, { "$ref": "#/components/parameters/Elevation" }, { "$ref": "#/components/parameters/TimeZone" }, { "$ref": "#/components/parameters/Lang" } ], "responses": { "200": { "description": "Successful response", "headers": { "X-Credits-Charged": { "description": "Number of API credits consumed by this request.", "schema": { "type": "number", "example": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AstronomyTimeSeriesResponse" }, "example": { "location": { "latitude": "40.76473", "longitude": "-74.00084", "country_name": "United States", "state_prov": "New York", "city": "New York", "locality": "Midtown West", "elevation": "9" }, "astronomy": [ { "date": "2026-03-18", "mid_night": "00:06", "night_end": "04:49", "morning": { "astronomical_twilight_begin": "04:49", "astronomical_twilight_end": "05:21", "nautical_twilight_begin": "05:21", "nautical_twilight_end": "05:53", "civil_twilight_begin": "05:53", "civil_twilight_end": "06:20", "blue_hour_begin": "05:42", "blue_hour_end": "06:03", "golden_hour_begin": "06:03", "golden_hour_end": "06:57" }, "sunrise": "06:20", "sunset": "19:00", "evening": { "golden_hour_begin": "18:23", "golden_hour_end": "19:16", "blue_hour_begin": "19:16", "blue_hour_end": "19:38", "civil_twilight_begin": "19:00", "civil_twilight_end": "19:27", "nautical_twilight_begin": "19:27", "nautical_twilight_end": "19:59", "astronomical_twilight_begin": "19:59", "astronomical_twilight_end": "20:31" }, "night_begin": "20:31", "sun_status": "-", "solar_noon": "12:40", "day_length": "12:40", "moon_phase": "WAXING_CRESCENT", "moonrise": "08:45", "moonset": "22:10", "moon_status": "-" }, { "date": "2026-03-19", "mid_night": "00:06", "night_end": "04:47", "morning": { "astronomical_twilight_begin": "04:47", "astronomical_twilight_end": "05:19", "nautical_twilight_begin": "05:19", "nautical_twilight_end": "05:51", "civil_twilight_begin": "05:51", "civil_twilight_end": "06:18", "blue_hour_begin": "05:40", "blue_hour_end": "06:01", "golden_hour_begin": "06:01", "golden_hour_end": "06:55" }, "sunrise": "06:18", "sunset": "19:02", "evening": { "golden_hour_begin": "18:25", "golden_hour_end": "19:18", "blue_hour_begin": "19:18", "blue_hour_end": "19:40", "civil_twilight_begin": "19:02", "civil_twilight_end": "19:29", "nautical_twilight_begin": "19:29", "nautical_twilight_end": "20:01", "astronomical_twilight_begin": "20:01", "astronomical_twilight_end": "20:33" }, "night_begin": "20:33", "sun_status": "-", "solar_noon": "12:40", "day_length": "12:44", "moon_phase": "WAXING_CRESCENT", "moonrise": "09:30", "moonset": "23:05", "moon_status": "-" } ] } }, "application/xml": { "schema": { "$ref": "#/components/schemas/AstronomyLookupResponse" }, "example": "\n \n 40.76473\n -74.00084\n United States\n New York\n New York\n Midtown West\n 9\n \n \n 2026-03-18\n 15:54:15.261\n 01:03\n 05:31\n \n 05:31\n 06:03\n 06:03\n 06:35\n 06:35\n 07:02\n 06:24\n 06:46\n 06:46\n 07:38\n \n 07:02\n 19:06\n \n 18:30\n 19:22\n 19:22\n 19:44\n 19:06\n 19:33\n 19:33\n 20:05\n 20:05\n 20:38\n \n 20:38\n -\n 13:04\n 12:04\n 33.35169743090959\n 148782269.19009596\n 234.07341944671086\n NEW_MOON\n 06:44\n 18:57\n -\n 31.430127664137917\n 374392.1525559059\n 237.27212480757834\n 39.582319837764366\n -0.07\n 357.01360045404493\n \n\n" } } }, "400": { "description": "Bad Request – Possible reasons include:\n - If the provided IPv4 or IPv6 address is invalid.\n - If special character(s) `( ) [ ] { } | ^ \\`` is passed in the\n API URL either as a parameter or its value.\n - If `dateStart` or `dateEnd` is not in the format `yyyy-MM-dd`.\n - If the span between `dateStart` and `dateEnd` is greater than\n **90 days**.\n - If the provided values for `lat` and `long` are not numbers,\n or fall outside the acceptable ranges.\n - If the provided `elevation` value exceeds **10,000 meters**.\n - If the provided `time_zone` is invalid or unrecognized.\n - If an invalid or unsupported `lang` parameter is provided.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "invalidIp": { "summary": "Invalid IPv4 or IPv6 address", "value": { "message": "Provided name, service or IP address '999.999.999.999' is not valid." } }, "specialCharacters": { "summary": "Invalid characters in request", "value": { "message": "Invalid character found in the request target." } }, "invalidDateFormat": { "summary": "Invalid date format", "value": { "message": "You must provide date in the 'yyyy-MM-dd' format" } }, "dateRangeExceeded": { "summary": "Date range exceeds 90 days", "value": { "message": "Date range cannot exceed 90 days." } }, "invalidCoordinates": { "summary": "Coordinates out of range", "value": { "message": "Longitude must be between -180 and 180 or latitude must be between -90 and 90." } }, "invalidElevation": { "summary": "Elevation exceeds maximum", "value": { "message": "Elevation cannot be greater than 10000 meters." } }, "invalidTimezone": { "summary": "Invalid timezone identifier", "value": { "message": "Check whether your input values are correct; time_zone_name = Europe/InvalidCity" } }, "invalidLang": { "summary": "Unsupported language parameter", "value": { "message": "This 'xx' lang is not valid. Please use 'en' as the default language." } } } } } }, "401": { "description": "Unauthorized – Possible reasons include:\n - Missing or invalid API key.\n - If your account has been disabled or locked by the admin.\n - When the request is made using an API key for a database\n subscription.\n - When the request is made on a paused subscription.\n - If your subscription trial has expired.\n - If your active-until date has passed.\n - A language other than English is specified in the `lang`\n parameter while using a Free/Developer plan API key.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "missingApiKey": { "summary": "Missing API key", "value": { "message": "Please provide an API key (as 'apiKey=YOUR_API_KEY' URL parameter) to use IPGeolocation API. To get your free API Key, sign up at https://app.ipgeolocation.io/login" } }, "invalidApiKey": { "summary": "Invalid API key", "value": { "message": "Provided API key is not valid. Contact technical support for assistance at support@ipgeolocation.io" } }, "lockedAccount": { "summary": "Account locked", "value": { "message": "Your account has been locked to use IPGeolocation API. Contact technical support for assistance at support@ipgeolocation.io" } }, "databaseSubscription": { "summary": "Database subscription key used", "value": { "message": "You cannot query IPGeolocation API on a database plan subscription." } }, "pausedSubscription": { "summary": "Subscription paused", "value": { "message": "Your subscription has been paused. Please resume your subscription to use IPGeolocation API." } }, "expiredSubscription": { "summary": "Subscription expired", "value": { "message": "Your subscription has expired at DATE. Please subscribe to a paid plan to continue using IPGeolocation API without interruption or contact technical support for assistance at support@ipgeolocation.io" } }, "freePlanLang": { "summary": "Non-English language on Free plan", "value": { "message": "This 'de' lang is not supported for your current subscription. Please use 'en' as the default language or upgrade your subscription to use this feature." } } } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "405": { "$ref": "#/components/responses/MethodNotAllowed" }, "423": { "$ref": "#/components/responses/Locked" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "499": { "$ref": "#/components/responses/ClientClosedRequest" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "502": { "$ref": "#/components/responses/BadGateway" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" }, "504": { "$ref": "#/components/responses/GatewayTimeout" }, "505": { "$ref": "#/components/responses/HttpVersionNotSupported" } } } } }, "components": { "parameters": { "Lat": { "name": "lat", "in": "query", "required": false, "description": "Latitude coordinate of the location. Must be provided together with\nthe `long` parameter.\n\nValid latitude values range from **-90 to 90**.\n", "schema": { "type": "number", "format": "float" }, "examples": { "none": { "summary": "Do not provide latitude", "value": "" }, "newYork": { "summary": "Latitude of New York", "value": 40.76473 }, "brisbane": { "summary": "Latitude of Brisbane", "value": -27.4748 } } }, "Long": { "name": "long", "in": "query", "required": false, "description": "Longitude coordinate of the location. Must be provided together with\nthe `lat` parameter.\n\nValid longitude values range from **-180 to 180**.\n", "schema": { "type": "number", "format": "float" }, "examples": { "none": { "summary": "Do not provide longitude", "value": "" }, "newYork": { "summary": "Longitude of New York", "value": -74.00084 }, "brisbane": { "summary": "Longitude of Brisbane", "value": 153.017 } } }, "Location": { "name": "location", "in": "query", "required": false, "description": "Address or location name used to determine the astronomical\ninformation. Typically a city-level or region-level address such as\n`New York, USA` or `London, UK`.\n\nWhen this parameter is used, the API returns a `location` object\ncontaining geolocation details alongside the `astronomy` object.\n", "schema": { "type": "string" }, "examples": { "none": { "summary": "Do not provide location", "value": "" }, "newYork": { "summary": "City address", "value": "New York, USA" }, "london": { "summary": "City address", "value": "London, UK" } } }, "Ip": { "name": "ip", "in": "query", "required": false, "description": "An IPv4 or IPv6 address used to resolve the location for the\nastronomical lookup. When omitted, the API resolves the public IP\nof the requesting client.\n\nWhen the lookup is performed using an IP address, the response\nincludes additional geolocation fields in the `location` object\nsuch as continent, country codes, district, and zipcode.\n", "schema": { "type": "string" }, "examples": { "none": { "summary": "Do not provide IP address", "value": "" }, "ipv4": { "summary": "IPv4 address", "value": "8.8.8.8" }, "ipv6": { "summary": "IPv6 address", "value": "2607:fb91:16c6:8860:e531:2d1d:4944:6c7c" } } }, "Date": { "name": "date", "in": "query", "required": false, "description": "Date for which to retrieve astronomical information.\n\nMust be in `yyyy-MM-dd` format. Defaults to the current date if\nnot provided. All astronomical information is calculated at the\ncurrent time of day at the resolved location.\n", "schema": { "type": "string", "format": "date" }, "examples": { "none": { "summary": "Use current date", "value": "" }, "specific": { "summary": "Specific date", "value": "2026-03-18" } } }, "DateStart": { "name": "dateStart", "in": "query", "required": true, "description": "Start date of the time series range.\n\nMust be in `yyyy-MM-dd` format. The maximum allowed span between\n`dateStart` and `dateEnd` is **90 days**.\n", "schema": { "type": "string", "format": "date" }, "examples": { "example": { "summary": "Start date", "value": "2026-03-18" } } }, "DateEnd": { "name": "dateEnd", "in": "query", "required": true, "description": "End date of the time series range.\n\nMust be in `yyyy-MM-dd` format. The maximum allowed span between\n`dateStart` and `dateEnd` is **90 days**.\n", "schema": { "type": "string", "format": "date" }, "examples": { "example": { "summary": "End date", "value": "2026-04-18" } } }, "Elevation": { "name": "elevation", "in": "query", "required": false, "description": "Elevation of the location above sea level in meters. Used to\nrefine astronomical calculations.\n\nDefaults to `0` if not provided. Maximum allowed value is\n**10,000 meters**. Negative values are treated as `0`.\n", "schema": { "type": "number", "format": "double", "default": 0, "minimum": 0, "maximum": 10000 }, "examples": { "none": { "summary": "Use default elevation (sea level)", "value": 0 }, "elevated": { "summary": "Custom elevation", "value": 1500 } } }, "TimeZone": { "name": "time_zone", "in": "query", "required": false, "description": "IANA timezone identifier used to convert all astronomical event\ntimestamps into the specified timezone.\n\nWhen provided, all event times (sunrise, sunset, moonrise, moonset,\ntwilight phases, solar noon, etc.) are returned as full date-time\nvalues (`yyyy-MM-dd HH:mm`) instead of time-only values (`HH:mm`),\nand a `time_zone` field is included in the `astronomy` object.\n\nThe geographic location used for astronomical calculations remains\nunchanged. Only the timestamp representation is converted.\n\nExample: `Europe/London`, `America/New_York`, `Asia/Karachi`.\n", "schema": { "type": "string" }, "examples": { "none": { "summary": "Use location's local timezone", "value": "" }, "london": { "summary": "Convert to London timezone", "value": "Europe/London" }, "newYork": { "summary": "Convert to New York timezone", "value": "America/New_York" } } }, "Lang": { "name": "lang", "in": "query", "required": false, "description": "Language code for translated location names in the `location` object.\nOnly applies when the lookup is performed via an IP address.\n\nDefaults to `en`. Non-English responses require a paid plan. Free\nplans always receive English regardless of this parameter. Unsupported\n`lang` values return HTTP 400.\n", "schema": { "type": "string", "default": "en", "enum": [ "en", "de", "ru", "ja", "fr", "cn", "es", "cs", "it", "ko", "fa", "pt" ] } } }, "responses": { "NotFound": { "description": "Not Found. Returned for one of the following reasons:\n - If the IPv4 or IPv6 address does not exist in the database.\n - If the IPv4 or IPv6 address is passed as a path variable instead\n of a URL parameter (`ip=`).\n - If the location address provided to the `location` parameter is\n invalid. A city-level or state-level address must be provided.\n - If the wrong endpoint is called that does not exist in the API.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "ipNotInDatabase": { "summary": "IP not found in database", "value": { "message": "Provided IPv4 or IPv6 address does not exist in our database." } }, "invalidLocation": { "summary": "Invalid location address", "value": { "message": "We couldn't find the location 'InvalidCity, XX'. Try a city or state level address only." } }, "wrongEndpoint": { "summary": "Incorrect or non-existent endpoint", "value": { "message": "No endpoint GET /v3/astronomy-invalid." } } } } } }, "MethodNotAllowed": { "description": "Method Not Allowed. Only the **GET** method is supported for\nAstronomy API endpoints. Any other HTTP method results in HTTP 405.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "message": "Request method 'POST' is not supported" } } } }, "Locked": { "description": "Locked. The provided IP address belongs to a bogon IP range or a\nprivate network and cannot be looked up.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "message": "'10.0.0.1' is a bogon IP address." } } } }, "TooManyRequests": { "description": "Too Many Requests. Returned for one of the following reasons:\n - The API usage limit has been reached for a free subscription or a\n paid subscription with status `past due`, `deleted`, or\n `trial expired`.\n - The surcharge API usage limit has been reached for the subscribed\n plan.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "usageLimitReached": { "summary": "API usage limit reached", "value": { "message": "You have exceeded the limit of PLAN_USAGE_LIMIT requests per PLAN_INTERVAL for your subscribed PLAN plan. Please throttle your requests or upgrade your plan to continue using IPGeolocation API without interruption." } }, "surchargeLimitReached": { "summary": "Surcharge usage limit reached", "value": { "message": "You have reached the surcharge amount limit of PLAN_USAGE_LIMIT_AND_SURCHARGE_LIMIT on your subscribed PLAN plan. Please throttle your requests or upgrade your plan to continue using IPGeolocation API without interruption." } } } } } }, "ClientClosedRequest": { "description": "The client closed the connection before the server finished processing\nthe request. This usually happens when the client sets a very short\nrequest or connection timeout. Increase the timeout on the client side.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "message": "Client closed the request before the server could respond." } } } }, "InternalServerError": { "description": "Internal Server Error. The server encountered an unexpected condition\nthat prevented it from fulfilling the request. If the issue persists,\ncontact support@ipgeolocation.io.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "message": "Something went wrong on the server side." } } } }, "BadGateway": { "description": "Bad Gateway. The API server received an invalid response from an\nupstream server. This is usually temporary.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "message": "Upstream service error. Please try again later." } } } }, "ServiceUnavailable": { "description": "Service Unavailable. The API is temporarily unavailable due to\nmaintenance or overload. Please try again later.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "message": "Service temporarily unavailable. Please try again later." } } } }, "GatewayTimeout": { "description": "Gateway Timeout. The API server did not receive a timely response\nfrom an upstream server.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "message": "The server timed out while processing the request." } } } }, "HttpVersionNotSupported": { "description": "HTTP Version Not Supported. The server does not support the HTTP\nprotocol version used in the request.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "message": "HTTP version not supported." } } } } }, "schemas": { "ErrorResponse": { "type": "object", "description": "Returned for any non-200 response. Contains only a human-readable\n`message`. Message text can vary by status and condition; examples\nin this spec are representative, not exhaustive, and should not be\ntreated as stable machine codes.\n", "required": [ "message" ], "properties": { "message": { "type": "string", "description": "Human-readable explanation of what went wrong.", "example": "Provided name, service or IP address '999.999.999.999' is not valid." } } }, "AstronomyLookupResponse": { "type": "object", "description": "Response returned by the single-date Astronomy Lookup API.\n\nContains a `location` object with geolocation details for the\nresolved location, and an `astronomy` object with astronomical\nevent times and positional data for the requested date.\n\nThe `location` object structure varies based on the lookup method:\n- Coordinate or location-based lookups return basic geographic fields.\n- IP-based lookups return extended geolocation fields including\n continent, country codes, district, and zipcode.\n", "properties": { "ip": { "type": "string", "description": "The IP address used for the astronomy lookup. Returned only when\nthe lookup is performed using the `ip` parameter or when the API\nresolves the caller's IP automatically (no parameters provided).\n", "example": "8.8.8.8" }, "location": { "$ref": "#/components/schemas/Location" }, "astronomy": { "$ref": "#/components/schemas/AstronomyData" } } }, "AstronomyTimeSeriesResponse": { "type": "object", "description": "Response returned by the Astronomy Time Series API.\n\nContains a `location` object and an `astronomy` array where each\nelement represents astronomical data for a single day within the\nrequested date range.\n\nNote that real-time positional data (sun/moon altitude, azimuth,\ndistance, parallactic angle, illumination) is not included in time\nseries responses.\n", "properties": { "ip": { "type": "string", "description": "The IP address used for the astronomy lookup. Returned only when\nthe lookup is performed using the `ip` parameter or when the API\nresolves the caller's IP automatically.\n", "example": "8.8.8.8" }, "location": { "$ref": "#/components/schemas/Location" }, "astronomy": { "type": "array", "description": "Array of daily astronomical records covering the requested date\nrange. Each entry contains event times for one calendar day.\n", "items": { "$ref": "#/components/schemas/AstronomyTimeSeriesEntry" } } } }, "Location": { "type": "object", "description": "Geolocation information associated with the resolved location.\n\nFor coordinate-based or location-string lookups, only basic geographic\nfields are returned (latitude, longitude, country, state, city, locality,\nelevation).\n\nFor IP-based lookups, extended fields are also returned including\ncontinent codes, country codes, district, zipcode, and other metadata.\n", "properties": { "location_string": { "type": "string", "description": "The location string provided in the request. Only present when the\n`location` query parameter was used.\n", "example": "New York, USA" }, "continent_code": { "type": "string", "description": "Two-letter continent code. Returned for IP-based lookups only.", "example": "NA" }, "continent_name": { "type": "string", "description": "Full name of the continent. Returned for IP-based lookups only.", "example": "North America" }, "country_code2": { "type": "string", "description": "ISO 3166-1 alpha-2 country code. Returned for IP-based lookups only.\n", "example": "US" }, "country_code3": { "type": "string", "description": "ISO 3166-1 alpha-3 country code. Returned for IP-based lookups only.\n", "example": "USA" }, "country_name": { "type": "string", "description": "Common name of the country.", "example": "United States" }, "country_name_official": { "type": "string", "description": "Official name of the country. Returned for IP-based lookups only.\n", "example": "United States of America" }, "is_eu": { "type": "boolean", "description": "Indicates whether the country is a member of the European Union.\nReturned for IP-based lookups only.\n" }, "state_prov": { "type": "string", "description": "State, province, or region name.", "example": "New York" }, "state_code": { "type": "string", "description": "Standardized state or region code. Returned for IP-based lookups only.\n", "example": "US-NY" }, "district": { "type": "string", "description": "District or administrative subdivision. Returned for IP-based\nlookups only.\n", "example": "Manhattan" }, "city": { "type": "string", "description": "City name of the location.", "example": "New York" }, "locality": { "type": "string", "description": "Smaller locality or neighborhood within the city.", "example": "Midtown West" }, "zipcode": { "type": "string", "description": "ZIP or postal code of the location. Returned for IP-based\nlookups only.\n", "example": "10001" }, "latitude": { "type": "string", "format": "float", "description": "Latitude coordinate of the resolved location.", "example": "40.76473" }, "longitude": { "type": "string", "format": "float", "description": "Longitude coordinate of the resolved location.", "example": "-74.00084" }, "elevation": { "type": "string", "description": "Elevation above sea level at the location, in meters.", "example": "9" } } }, "TwilightPhase": { "type": "object", "description": "Twilight phase times for either the morning (pre-sunrise) or evening\n(post-sunset) period.\n\nIncludes astronomical, nautical, and civil twilight windows, as well\nas blue hour and golden hour windows commonly used in photography.\n\nAll times are in `HH:mm` format by default. When the `time_zone`\nparameter is provided, times are returned as full date-time values\nin `yyyy-MM-dd HH:mm` format.\n", "properties": { "astronomical_twilight_begin": { "type": "string", "description": "Start of astronomical twilight. In the morning, this marks the\nend of night; in the evening, this marks the start of night sky.\n", "example": "04:49" }, "astronomical_twilight_end": { "type": "string", "description": "End of astronomical twilight.", "example": "05:21" }, "nautical_twilight_begin": { "type": "string", "description": "Start of nautical twilight, when the horizon first becomes visible.\n", "example": "05:21" }, "nautical_twilight_end": { "type": "string", "description": "End of nautical twilight.", "example": "05:53" }, "civil_twilight_begin": { "type": "string", "description": "Start of civil twilight, when there is enough light for outdoor\nactivities without artificial lighting.\n", "example": "05:53" }, "civil_twilight_end": { "type": "string", "description": "End of civil twilight.", "example": "06:20" }, "blue_hour_begin": { "type": "string", "description": "Start of the blue hour, a period of soft diffused light with a\nblue color tone.\n", "example": "05:42" }, "blue_hour_end": { "type": "string", "description": "End of the blue hour.", "example": "06:03" }, "golden_hour_begin": { "type": "string", "description": "Start of the golden hour, a period of warm low-angle light\nfavored by photographers.\n", "example": "06:03" }, "golden_hour_end": { "type": "string", "description": "End of the golden hour.", "example": "06:57" } } }, "AstronomyData": { "type": "object", "description": "Astronomical data for the resolved location and requested date.\n\nIncludes event times for sunrise, sunset, moonrise, moonset,\ntwilight phases, golden hour, blue hour, solar noon, and\nastronomical midnight, as well as real-time positional data\nfor the Sun and Moon at the current time of day.\n\nAll timestamp fields (except `current_time` and `day_length`) are\nin `HH:mm` format by default. When the `time_zone` parameter is\nprovided, they are returned as full date-time values in\n`yyyy-MM-dd HH:mm` format.\n", "properties": { "time_zone": { "type": "string", "description": "The IANA timezone identifier used for timestamp conversion.\nThis field appears only when the `time_zone` query parameter\nwas provided in the request.\n", "example": "Europe/London" }, "date": { "type": "string", "description": "The date for which astronomical data is returned, in `yyyy-MM-dd` format.", "example": "2026-03-18" }, "current_time": { "type": "string", "description": "Current local time at the resolved location in `HH:mm:ss.SSS` format.\nUsed as the reference time for real-time positional calculations\n(altitude, azimuth, distance).\n", "example": "10:15:00.000" }, "mid_night": { "type": "string", "description": "Astronomical midnight (nadir) for the given date, in `HH:mm` format.\n", "example": "00:06" }, "night_end": { "type": "string", "description": "End of night / start of astronomical twilight in the morning,\nin `HH:mm` format.\n", "example": "04:49" }, "morning": { "$ref": "#/components/schemas/TwilightPhase" }, "sunrise": { "type": "string", "description": "Time at which the sun rises at the resolved location, in `HH:mm` format.\n", "example": "06:20" }, "sunset": { "type": "string", "description": "Time at which the sun sets at the resolved location, in `HH:mm` format.\n", "example": "19:00" }, "evening": { "$ref": "#/components/schemas/TwilightPhase" }, "night_begin": { "type": "string", "description": "Start of night / end of astronomical twilight in the evening,\nin `HH:mm` format.\n", "example": "20:31" }, "sun_status": { "type": "string", "description": "Represents the current state of the sun relative to the horizon:\n\n- `\"-\"` — Normal day with both sunrise and sunset occurring.\n- `\"Always above the twilight angle\"` — The sun does not set\n (perpetual daylight, e.g. polar summer).\n- `\"Always below the twilight angle\"` — The sun does not rise\n within the current 24-hour period (e.g. polar night).\n", "example": "-" }, "solar_noon": { "type": "string", "description": "The time when the sun is at its highest point in the sky,\nin `HH:mm` format.\n", "example": "12:40" }, "day_length": { "type": "string", "description": "Total length of daylight for the date, from sunrise to sunset,\nin `HH:mm` format.\n", "example": "12:40" }, "sun_altitude": { "type": "number", "format": "float", "description": "The sun's altitude angle above the horizon at `current_time`,\nmeasured in degrees. Negative values indicate the sun is below\nthe horizon.\n", "example": 42.5 }, "sun_distance": { "type": "number", "format": "float", "description": "Distance from Earth to the sun at `current_time`, in kilometers.\n", "example": 148900000.0 }, "sun_azimuth": { "type": "number", "format": "float", "description": "The azimuth angle of the sun at `current_time`, indicating its\ncompass direction in degrees (0° = North, 90° = East, etc.).\n", "example": 150.3 }, "moon_phase": { "type": "string", "description": "The current phase of the moon, indicating its position in the\nlunar cycle.\n", "enum": [ "NEW_MOON", "WAXING_CRESCENT", "FIRST_QUARTER", "WAXING_GIBBOUS", "FULL_MOON", "WANING_GIBBOUS", "LAST_QUARTER", "WANING_CRESCENT" ], "example": "WAXING_CRESCENT" }, "moonrise": { "type": "string", "description": "Time at which the moon rises at the resolved location, in `HH:mm`\nformat. Returns `\"-:-\"` if the moon does not rise on this date.\n", "example": "08:45" }, "moonset": { "type": "string", "description": "Time at which the moon sets at the resolved location, in `HH:mm`\nformat. Returns `\"-:-\"` if the moon does not set on this date.\n", "example": "22:10" }, "moon_status": { "type": "string", "description": "Represents the current state of the moon relative to the horizon:\n\n- `\"-\"` — Normal day with both moonrise and moonset occurring.\n- `\"Always above the horizon\"` — The moon does not set within\n the current 24-hour period.\n- `\"Always below the horizon\"` — The moon does not rise within\n the current 24-hour period.\n", "example": "-" }, "moon_altitude": { "type": "number", "format": "float", "description": "The moon's altitude angle above the horizon at `current_time`,\nmeasured in degrees. Negative values indicate the moon is below\nthe horizon.\n", "example": 15.2 }, "moon_distance": { "type": "number", "format": "float", "description": "Distance from Earth to the moon at `current_time`, in kilometers.\n", "example": 384400.0 }, "moon_azimuth": { "type": "number", "format": "float", "description": "The azimuth angle of the moon at `current_time`, indicating its\ncompass direction in degrees.\n", "example": 220.5 }, "moon_parallactic_angle": { "type": "number", "format": "float", "description": "The angle between the celestial pole and the moon's position\nrelative to the observer's location, measured in degrees.\n", "example": 30.1 }, "moon_illumination_percentage": { "type": "string", "description": "The percentage of the moon's surface illuminated by sunlight\nas viewed from Earth. Returned as a string with two decimal\nplaces. Negative values indicate a waning phase.\n", "example": "25.40" }, "moon_angle": { "type": "number", "format": "float", "description": "The angular diameter of the moon as observed from Earth,\nmeasured in degrees.\n", "example": 0.52 } } }, "AstronomyTimeSeriesEntry": { "type": "object", "description": "Astronomical data for a single calendar day within the time series\nresponse.\n\nContains event times for sunrise, sunset, moonrise, moonset,\ntwilight phases, solar noon, and day length.\n\nNote: Real-time positional data (sun/moon altitude, azimuth,\ndistance, parallactic angle, illumination percentage, and moon\nangle) is not included in time series entries.\n", "properties": { "date": { "type": "string", "description": "The calendar date for this entry, in `yyyy-MM-dd` format.", "example": "2026-03-18" }, "mid_night": { "type": "string", "description": "Astronomical midnight (nadir) for the given date.", "example": "00:06" }, "night_end": { "type": "string", "description": "End of night / start of astronomical twilight in the morning.", "example": "04:49" }, "morning": { "$ref": "#/components/schemas/TwilightPhase" }, "sunrise": { "type": "string", "description": "Time at which the sun rises, in `HH:mm` format. Returns `\"-:-\"`\nif the sun does not rise on this date.\n", "example": "06:20" }, "sunset": { "type": "string", "description": "Time at which the sun sets, in `HH:mm` format. Returns `\"-:-\"`\nif the sun does not set on this date.\n", "example": "19:00" }, "evening": { "$ref": "#/components/schemas/TwilightPhase" }, "night_begin": { "type": "string", "description": "Start of night / end of astronomical twilight in the evening.", "example": "20:31" }, "sun_status": { "type": "string", "description": "Current state of the sun relative to the horizon. See\n`AstronomyData.sun_status` for possible values.\n", "example": "-" }, "solar_noon": { "type": "string", "description": "Time when the sun is at its highest point in the sky.", "example": "12:40" }, "day_length": { "type": "string", "description": "Total daylight duration from sunrise to sunset, in `HH:mm` format.", "example": "12:40" }, "moon_phase": { "type": "string", "description": "The phase of the moon on this date.", "enum": [ "NEW_MOON", "WAXING_CRESCENT", "FIRST_QUARTER", "WAXING_GIBBOUS", "FULL_MOON", "WANING_GIBBOUS", "LAST_QUARTER", "WANING_CRESCENT" ], "example": "WAXING_CRESCENT" }, "moonrise": { "type": "string", "description": "Time at which the moon rises, in `HH:mm` format. Returns `\"-:-\"`\nif the moon does not rise on this date.\n", "example": "08:45" }, "moonset": { "type": "string", "description": "Time at which the moon sets, in `HH:mm` format. Returns `\"-:-\"`\nif the moon does not set on this date.\n", "example": "22:10" }, "moon_status": { "type": "string", "description": "Current state of the moon relative to the horizon. See\n`AstronomyData.moon_status` for possible values.\n", "example": "-" } } } }, "securitySchemes": { "ApiKeyAuth": { "type": "apiKey", "in": "query", "name": "apiKey", "description": "API key passed as the `apiKey` query parameter. Get yours from the\n[IPGeolocation dashboard](https://app.ipgeolocation.io/). For\nclient-side usage on paid plans, consider using Request Origin (CORS)\nauthentication to avoid exposing your key." } } } }