{ "swagger": "2.0", "info": { "title": "Maps Geolocation", "version": "1.0", "description": "Azure Maps Geolocation REST APIs", "x-typespec-generated": [ { "emitter": "@azure-tools/typespec-autorest" } ] }, "schemes": [ "https" ], "x-ms-parameterized-host": { "hostTemplate": "{endpoint}", "useSchemePrefix": false, "parameters": [ { "name": "endpoint", "in": "path", "description": "The Azure Maps service hostname. Use `https://atlas.microsoft.com` for the Azure public cloud. To target a specific Azure Maps geography or a sovereign cloud, see [Azure Maps geographic scope](https://learn.microsoft.com/azure/azure-maps/geographic-scope).", "required": true, "type": "string", "format": "uri", "default": "https://atlas.microsoft.com", "x-ms-skip-url-encoding": true } ] }, "produces": [ "application/json" ], "consumes": [ "application/json" ], "security": [ { "AadToken": [ "https://atlas.microsoft.com/.default" ] }, { "SharedKey": [] }, { "SasToken": [] } ], "securityDefinitions": { "AadToken": { "type": "oauth2", "description": "These are the [Microsoft Entra OAuth 2.0](https://docs.microsoft.com/azure/active-directory/develop/v1-overview) Flows. When paired with [Azure role-based access](https://docs.microsoft.com/azure/role-based-access-control/overview) control it can be used to control access to Azure Maps REST APIs. Azure role-based access controls are used to designate access to one or more Azure Maps resource account or sub-resources. Any user, group, or service principal can be granted access via a built-in role or a custom role composed of one or more permissions to Azure Maps REST APIs.\n\nTo implement scenarios, we recommend viewing [authentication concepts](https://aka.ms/amauth). In summary, this security definition provides a solution for modeling application(s) via objects capable of access control on specific APIs and scopes.\n\n> [!NOTE]\n>\n> * This security definition **requires** the use of the `x-ms-client-id` header to indicate which Azure Maps resource the application is requesting access to. This can be acquired from the [Maps management API](https://aka.ms/amauthdetails).\n> * The `Authorization URL` is specific to the Azure public cloud instance. Sovereign clouds have unique Authorization URLs and Microsoft Entra ID configurations.\n> * The Azure role-based access control is configured from the [Azure management plane](https://aka.ms/amrbac) via Azure portal, PowerShell, CLI, Azure SDKs, or REST APIs.\n> * Usage of the [Azure Maps Web SDK](https://aka.ms/amaadmc) allows for configuration based setup of an application for multiple use cases.\n> * For more information on Microsoft identity platform, see [Microsoft identity platform overview](https://learn.microsoft.com/entra/identity-platform/v2-overview).", "flow": "implicit", "authorizationUrl": "https://login.microsoftonline.com/common/oauth2/authorize", "scopes": { "https://atlas.microsoft.com/.default": "" } }, "SasToken": { "type": "apiKey", "description": "This is a shared access signature token created from the List SAS operation on the [Azure Maps resource](https://aka.ms/amauth) through the Azure management plane via Azure portal, PowerShell, CLI, Azure SDKs, or REST APIs.\n\nWith this token, any application is authorized to access with Azure role-based access controls and fine-grain control to the expiration, rate, and region(s) of use for the particular token. In other words, the SAS Token can be used to allow applications to control access in a more secured way than the shared key.\n\nFor publicly exposed applications, our recommendation is to configure a specific list of allowed origins on the [Map account resource](https://aka.ms/amauth) to limit rendering abuse and regularly renew the SAS Token.", "name": "SAS Token", "in": "header" }, "SharedKey": { "type": "apiKey", "description": "This is a shared key that is provisioned when you [Create an Azure Maps account](https://docs.microsoft.com/azure/azure-maps/quick-demo-map-app#create-an-azure-maps-account) in the Azure portal or using PowerShell, CLI, Azure SDKs, or REST API.\n\nWith this key, any application can access all REST API. In other words, this key can be used as a master key in the account that they are issued in.\n\nFor publicly exposed applications, our recommendation is to use the [confidential client applications](https://docs.microsoft.com/azure/azure-maps/authentication-best-practices#confidential-client-applications) approach to access Azure Maps REST APIs so your key can be securely stored.", "name": "subscription-key", "in": "header" } }, "tags": [], "paths": { "/geolocation/ip/{format}": { "get": { "operationId": "Geolocation_GetIPToLocation", "summary": "Use to get the ISO country/region code for a given IP address.", "description": "The `Get IP To Location` API is an HTTP `GET` request that returns the ISO\ncountry/region code for a given IP address. Developers can use this information\nto block or modify content based on the geographical location from which the\napplication is accessed.", "parameters": [ { "$ref": "#/parameters/Azure.Core.Foundations.ApiVersionParameter" }, { "name": "x-ms-client-id", "in": "header", "description": "Indicates the account intended for use with the Microsoft Entra ID security\nmodel. This unique ID for the Azure Maps account can be obtained from the\n[Azure Maps management plane Account API](/rest/api/maps-management/accounts).\nFor more information on using Microsoft Entra ID security in Azure Maps, see\n[Manage authentication in Azure\nMaps](/azure/azure-maps/how-to-manage-authentication).", "required": false, "type": "string", "x-ms-client-name": "clientId" }, { "name": "format", "in": "path", "description": "Desired format of the response. Only `json` format is supported.", "required": true, "type": "string", "default": "json", "enum": [ "json" ], "x-ms-enum": { "name": "JsonFormat", "modelAsString": true, "values": [ { "name": "json", "value": "json", "description": "[The JavaScript Object Notation Data Interchange\nFormat](https://tools.ietf.org/html/rfc8259)" } ] } }, { "name": "ip", "in": "query", "description": "The IP address. Both IPv4 and IPv6 are allowed.", "required": true, "type": "string", "x-ms-client-name": "ipAddress" } ], "responses": { "200": { "description": "The request has succeeded.", "schema": { "$ref": "#/definitions/IpAddressToLocationResult" } }, "default": { "description": "An unexpected error response.", "schema": { "$ref": "#/definitions/ErrorResponse" } } }, "x-ms-examples": { "Successfully retrieve country/region code from IP address": { "$ref": "./examples/GetIpToLocation.json" } } } } }, "definitions": { "CountryRegion": { "type": "object", "description": "The object containing the country/region information.", "properties": { "isoCode": { "type": "string", "description": "The IP address's 2-character country or region code ([ISO\n3166-1](https://www.iso.org/iso-3166-country-codes.html)). Note that IP\naddresses in ranges reserved for special purposes will return Null for\ncountry/region.", "readOnly": true } } }, "ErrorAdditionalInfo": { "type": "object", "description": "The resource management error additional info.", "properties": { "type": { "type": "string", "description": "The additional info type.", "readOnly": true }, "info": { "type": "object", "description": "The additional info.", "additionalProperties": { "type": "string" }, "readOnly": true } } }, "ErrorDetail": { "type": "object", "description": "The error detail.", "properties": { "code": { "type": "string", "description": "The error code.", "readOnly": true }, "message": { "type": "string", "description": "The error message.", "readOnly": true }, "target": { "type": "string", "description": "The error target.", "readOnly": true }, "details": { "type": "array", "description": "The error details.", "items": { "$ref": "#/definitions/ErrorDetail" }, "readOnly": true }, "additionalInfo": { "type": "array", "description": "The error additional info.", "items": { "$ref": "#/definitions/ErrorAdditionalInfo" }, "readOnly": true } } }, "ErrorResponse": { "type": "object", "description": "Common error response for all Azure Resource Manager APIs to return error\ndetails for failed operations. (This also follows the OData error response\nformat.).", "properties": { "error": { "$ref": "#/definitions/ErrorDetail", "description": "The error object." } } }, "IpAddressToLocationResult": { "type": "object", "description": "This object is returned from a successful call to IP Address to country/region\nAPI", "properties": { "countryRegion": { "$ref": "#/definitions/CountryRegion", "description": "The object containing the country/region information.", "readOnly": true }, "ipAddress": { "type": "string", "description": "The IP Address of the request.", "readOnly": true } } } }, "parameters": { "Azure.Core.Foundations.ApiVersionParameter": { "name": "api-version", "in": "query", "description": "The API version to use for this operation.", "required": true, "type": "string", "minLength": 1, "x-ms-parameter-location": "method", "x-ms-client-name": "apiVersion" } } }