---
title: "Geolocation API"
description: "API for approximate location detection using IP addresses."
---

> For AI agents: a documentation index is available at [/llms.txt](https://docs.maptiler.com/llms.txt). Markdown versions of all pages are available by appending .md to any URL.

# Geolocation API

The MapTiler **Geolocation API** makes it possible to get approximate location of the incoming request, so you can localize your maps and applications. See the [intro to IP geolocation](https://docs.maptiler.com/guides/location-services/elevation/) to learn how geolocation works and what you can use it for.

## How to use the API

-   Directly from your web or backend applications.
-   Via the [Geolocation API client](https://docs.maptiler.com/client-js/#%EF%B8%8F%EF%B8%8F-geolocation) library, which wraps the API calls in ready-made functions for easier use in JavaScript. Recommended if you don’t need a map.
-   With our complete map [SDK JS](https://docs.maptiler.com/sdk-js/). This is the best choice if you want the geolocation service plus a map. See related [code examples](https://docs.maptiler.com/sdk-js/examples/?q=geolocation) for inspiration.

Key

You need a **MapTiler API key** to use this service. [Get it here](https://cloud.maptiler.com/account/keys/) and [learn how to secure it](https://docs.maptiler.com/guides/credentials/api-key/#secure-key).

* * *

## Geolocation API reference

  Scalar API Reference

-   [
    
    Introduction
    
    ](#description/introduction)
-   [
    
    Geolocation
    
    ](#tag/geolocation)
    
    Close Group - Geolocation
    
    -   [
        
        IP Geolocation
        
        HTTP Method:  GET](#tag/geolocation/GET/geolocation/ip.json)

[Powered by Scalar](https://www.scalar.com)

v1.0

OpenAPI 3.1.0

# MapTiler API

[Support](mailto:support@maptiler.com)

[](https://docs.maptiler.com/support/requests/)

[Terms of Service](https://www.maptiler.com/terms/)

Server

Server:https://api.maptiler.com

MapTiler API

## 

AuthenticationRequired

Selected Auth Type: key

<table class="mb-0 grid min-h-8 auto-rows-auto" role="presentation" style="grid-template-columns:1fr;"><tbody><tr class="group contents"><td class="box-content min-h-8 min-w-8 border-l-0 border-t border-b-0 border-r flex text-base/5 last:border-r-0 group-last:border-b-transparent p-0 m-0 relative max-h-[auto] group-[.alert]:bg-b-alert group-[.error]:bg-b-danger" style="" aria-label="Your own API key from https://cloud.maptiler.com/"><div class="group/summary flex gap-0.5 flex-row items-baseline auth-description bg-b-1 text-c-2 min-w-0 flex-1 px-3 py-1.25" style=""><div class="markdown line-clamp-(--markdown-clamp) markdown-summary truncate" style="--markdown-clamp:1;" controlled="false" modelvalue="false" truncated="false" id="scalar-refs-0-9"><p>Your own API key from <a href="https://cloud.maptiler.com/" rel="nofollow" target="_blank">https://cloud.maptiler.com/</a></p></div></div></td></tr><tr class="group contents"><td class="box-content max-h-8 min-h-8 min-w-8 border-l-0 border-b-0 border-r text-base/5 last:border-r-0 group-last:border-b-transparent p-0 m-0 relative flex border-t group-[.alert]:bg-b-alert group-[.error]:bg-b-danger" style="" data-v-a6f4752a=""><div class="text-c-1 flex items-center pr-0 pl-3" for="scalar-refs-0-10" data-v-a6f4752a=""><label for="scalar-refs-0-10">Name </label>:</div><div class="relative flex min-w-0 flex-1" data-v-a6f4752a=""><div id="scalar-refs-0-10" class="text-c-1 disabled:text-c-2 peer w-full min-w-0 border-none -outline-offset-1 code-input-lite group/code-input-lite peer relative w-full leading-[1.44] -outline-offset-1 has-[:focus-visible]:rounded-[4px] has-[:focus-visible]:outline code-input-lite--empty" data-v-4dfd05a3=""><div aria-autocomplete="list" class="code-input-lite__editor" contenteditable="true" data-placeholder="api-key" role="combobox" spellcheck="false" data-v-4dfd05a3=""></div></div></div><button aria-disabled="false" type="button" class="scalar-icon-button grid aspect-square cursor-pointer scalar-button-ghost bg-transparent text-c-2 active:text-c-1 hover:text-c-1 size-8 m-1 -outline-offset-2 rounded-lg -ml-.25 h-6 w-6 self-center p-1.25" style="" data-v-a6f4752a=""><svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 256 256" fill="currentColor" width="1em" height="1em" aria-hidden="true" role="presentation" class="size-full" style=""><g><path d="M205.66,194.34a8,8,0,0,1-11.32,11.32L128,139.31,61.66,205.66a8,8,0,0,1-11.32-11.32L116.69,128,50.34,61.66A8,8,0,0,1,61.66,50.34L128,116.69l66.34-66.35a8,8,0,0,1,11.32,11.32L139.31,128Z"></path></g></svg><span class="sr-only">Clear Value</span></button></td></tr><tr class="group contents"><td class="box-content max-h-8 min-h-8 min-w-8 border-l-0 border-t border-b-0 border-r text-base/5 last:border-r-0 group-last:border-b-transparent p-0 m-0 relative flex group-[.alert]:bg-b-alert group-[.error]:bg-b-danger" style="" data-v-a6f4752a=""><div class="text-c-1 flex items-center pr-0 pl-3" for="scalar-refs-0-11" data-v-a6f4752a=""><label for="scalar-refs-0-11">Value </label>:</div><div class="relative flex min-w-0 flex-1" data-v-a6f4752a=""><input placeholder="QUxMIFlPVVIgQkFTRSBBUkUgQkVMT05HIFRPIFVT" id="scalar-refs-0-11" autocomplete="off" class="text-c-1 disabled:text-c-2 peer w-full min-w-0 border-none px-2 py-1.25 -outline-offset-1 scalar-password-input" data-1p-ignore="" spellcheck="false" type="text" value="YOUR_MAPTILER_API_KEY" data-v-a6f4752a=""></div><button aria-disabled="false" type="button" class="scalar-icon-button grid aspect-square cursor-pointer scalar-button-ghost bg-transparent text-c-2 active:text-c-1 hover:text-c-1 size-8 m-1 -outline-offset-2 rounded-lg -ml-.25 h-6 w-6 self-center p-1.25" style="" data-v-a6f4752a=""><svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 256 256" fill="currentColor" width="1em" height="1em" aria-hidden="true" role="presentation" class="size-full" style=""><g><path d="M205.66,194.34a8,8,0,0,1-11.32,11.32L128,139.31,61.66,205.66a8,8,0,0,1-11.32-11.32L116.69,128,50.34,61.66A8,8,0,0,1,61.66,50.34L128,116.69l66.34-66.35a8,8,0,0,1,11.32,11.32L139.31,128Z"></path></g></svg><span class="sr-only">Clear Value</span></button><button aria-disabled="false" type="button" class="scalar-icon-button grid aspect-square cursor-pointer scalar-button-ghost bg-transparent text-c-2 active:text-c-1 hover:text-c-1 size-8 m-1 -outline-offset-2 rounded-lg -ml-.5 mr-1.25 h-6 w-6 self-center p-1.25" style="" data-testid="data-table-password-toggle" data-v-a6f4752a=""><svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 256 256" fill="currentColor" width="1em" height="1em" aria-hidden="true" role="presentation" class="size-full" style=""><g><path d="M247.31,124.76c-.35-.79-8.82-19.58-27.65-38.41C194.57,61.26,162.88,48,128,48S61.43,61.26,36.34,86.35C17.51,105.18,9,124,8.69,124.76a8,8,0,0,0,0,6.5c.35.79,8.82,19.57,27.65,38.4C61.43,194.74,93.12,208,128,208s66.57-13.26,91.66-38.34c18.83-18.83,27.3-37.61,27.65-38.4A8,8,0,0,0,247.31,124.76ZM128,192c-30.78,0-57.67-11.19-79.93-33.25A133.47,133.47,0,0,1,25,128,133.33,133.33,0,0,1,48.07,97.25C70.33,75.19,97.22,64,128,64s57.67,11.19,79.93,33.25A133.46,133.46,0,0,1,231.05,128C223.84,141.46,192.43,192,128,192Zm0-112a48,48,0,1,0,48,48A48.05,48.05,0,0,0,128,80Zm0,80a32,32,0,1,1,32-32A32,32,0,0,1,128,160Z"></path></g></svg><span class="sr-only">Show Password</span></button></td></tr></tbody></table>

Client Libraries

Shell

Ruby

Node.js

PHP

Python

MoreSelect from all clients

Shell Curl

## Geolocation

​Copy link

Geolocation Operations

-   get/geolocation/ip.json

### IP Geolocation

​Copy link

Auth Required

Obtain information about visitor's location based on IP address of the incoming request.

Query Parameters

-   elevationCopy link to elevation
    
    Type: boolean
    
    Include elevation (in meters) in the results.
    

Responses

-   200
    
    application/json
    
-   403
    
    Key is missing, invalid or restricted
    

Request Example for get/geolocation/ip.json

Shell Curl

```curl
curl 'https://api.maptiler.com/geolocation/ip.json?key=YOUR_MAPTILER_API_KEY'
```

Copy

Copy

Test Request(get /geolocation/ip.json)

Status: 200Status: 403

Show Schema 

```json
{
  "country": "Switzerland",
  "country_code": "CH",
  "country_bounds": [
    5.95538,
    45.818852,
    10.490936,
    47.809357
  ],
  "country_languages": [
    "de",
    "fr",
    "it"
  ],
  "continent": "Europe",
  "continent_code": "EU",
  "eu": false,
  "city": "Zurich",
  "latitude": 47.36667,
  "longitude": 8.55,
  "postal": "8000",
  "region": "Zurich",
  "region_code": "ZH",
  "timezone": "Europe/Zurich",
  "elevation": 433
}
```

JSONCopy

JSONCopy

![](https://docs.maptiler.com/assets/img/open-api.png)

Using the OpenAPI Specification?

Get the [openapi.yaml](https://docs.maptiler.com/_data/cloud/api/openapi.yml)