<!--
{
  "availability" : [
    "MapKit JS: 5.0.0 -"
  ],
  "documentType" : "symbol",
  "framework" : "MapKitJS",
  "identifier" : "/documentation/MapKitJS/Geocoder",
  "metadataVersion" : "0.1.0",
  "role" : "Class",
  "symbol" : {
    "kind" : "Class",
    "modules" : [
      "MapKit JS"
    ],
    "preciseIdentifier" : "cl/mapkit.Geocoder"
  },
  "title" : "Geocoder"
}
-->

# Geocoder

A geocoder that converts human-readable addresses to geographic coordinates, and vice versa.

```
class Geocoder extends Service
```

## Overview

When using MapKit JS to show Apple Maps on a website, the geocoder handles forward and reverse geocoding. Because the framework performs geocoding on the server, the geocoder requires a network connection and handles calls asynchronously.

Provide context to the geocoder to get the most relevant results. The geocoder can obtain context from these sources:

- **The user’s location in the browser’s Geolocation API.** The geocoder assigns higher relevancy to results near the user’s location. Asking for the user’s location requires the user’s permission. If you enable this option, the browser asks the user for permission (some browsers remember this setting for a day). MapKit JS disables this option by default.
- **Lookup options.** Your website can provide context in the geocoder lookup options as a coordinate or region. For example, if a user types *Brisbane* into a map text field and the web page invokes the geocoder without context, the geocoder returns the major city in Australia. If, however, the map displays San Francisco and its environs, a geocoding request with this region as context returns the nearby city of Brisbane instead.
- **The user’s IP address.** Of the three forms of context, this is the least accurate, but the only one certain to be present. The user’s IP address is a granular IP location that the system doesn’t log or store.

## Topics

### Creating a geocoder object

[`constructor(options?: ServiceConstructorOptions);`](/documentation/MapKitJS/Geocoder/GeocoderConstructor)

Creates a geocoder object and sets optional language and user location properties.

[`interface ServiceConstructorOptions`](/documentation/MapKitJS/ServiceConstructorOptions)

Common options you provide when you create a service object.

[`get getsUserLocation(): boolean;
set getsUserLocation(value: boolean);`](/documentation/MapKitJS/Service/getsUserLocation)

A Boolean value that indicates whether the request returns results near a person’s location.

[`get language(): string | null;
set language(value: string | null);`](/documentation/MapKitJS/Service/language)

A language ID that determines the language to use for displaying addresses.

### Getting geocoder results

[`lookup(
    place: string,
    options?: GeocoderLookupOptions,
): Promise<GeocoderResponse>;`](/documentation/MapKitJS/Geocoder/lookup)

Converts an address to geographic coordinates.

[`interface GeocoderLookupOptions`](/documentation/MapKitJS/GeocoderLookupOptions)

Options that constrain geocoder lookup results to a specific area or a specific language.

[`reverseLookup(
    coordinate: Coordinate,
    options?: GeocoderReverseLookupOptions,
): Promise<GeocoderResponse>;`](/documentation/MapKitJS/Geocoder/reverseLookup)

Converts a geographic coordinate to an address.

[`interface GeocoderReverseLookupOptions`](/documentation/MapKitJS/GeocoderReverseLookupOptions)

An option that constrains reverse lookup results to a specific language.

[`interface GeocoderResponse`](/documentation/MapKitJS/GeocoderResponse)

The response from a geocoder lookup or reverse lookup.

### Canceling a geocoder request

[`cancel(promise: Promise<unknown>): boolean;`](/documentation/MapKitJS/Service/cancel)

Cancels a request using the provided request promise.

### Deprecated

[`lookup(
    place: string,
    callback: (
        error: Error | null,
        result: GeocoderResponse | null,
    ) => void,
    options?: GeocoderLookupOptions,
): Promise<GeocoderResponse>;`](/documentation/MapKitJS/Geocoder/lookup1)

Converts an address to geographic coordinates.

[`reverseLookup(
    coordinate: CoordinateData,
    callback: (
        error: Error | null,
        result: GeocoderResponse | null,
    ) => void,
    options?: GeocoderReverseLookupOptions,
): Promise<GeocoderResponse>;`](/documentation/MapKitJS/Geocoder/reverseLookup1)

Converts a geographic coordinate to an address.

## Relationships

### Inherits From

[`Service`](/documentation/MapKitJS/Service)

---

Copyright &copy; 2026 Apple Inc. All rights reserved. | [Terms of Use](https://www.apple.com/legal/internet-services/terms/site.html) | [Privacy Policy](https://www.apple.com/privacy/privacy-policy)