Response format

https://geocoder.api.mappable.world/v1/?apikey=YOUR_API_KEY&geocode=Dubai, Mohammed Bin Rashid Boulevard, 1&lang=en_US 

In this case, the geocoder response will look like this:

{
  "response": {
    "GeoObjectCollection": {
      "metaDataProperty": {
        "GeocoderResponseMetaData": {
          "request": "Dubai, Mohammed Bin Rashid Boulevard, 1",
          "found": "1",
          "results": "10"
        }
      },
      "featureMember": [
        {
          "GeoObject": {
            "metaDataProperty": {
              "GeocoderMetaData": {
                "kind": "house",
                "text": "UAE, Dubai, Mohammed Bin Rashid Boulevard, 1",
                "precision": "exact",
                "Address": {
                  "country_code": "UAE",
                  "postal_code": "00000",
                  "formatted": "Dubai, Mohammed Bin Rashid Boulevard, 1",
                  "Components": [
                    {
                      "kind": "country",
                      "name": "UAE"
                    },
                    {
                      "kind": "province",
                      "name": "Emirate of Dubai"
                    },
                    {
                      "kind": "province",
                      "name": "Dubai"
                    },
                    {
                      "kind": "locality",
                      "name": "Dubai"
                    },
                    {
                      "kind": "street",
                      "name": "Mohammed Bin Rashid Boulevard"
                    },
                    {
                      "kind": "house",
                      "name": "1"
                    }
                  ]
                },
                "AddressDetails": {
                  "Country": {
                    "AddressLine": "Dubai, Mohammed Bin Rashid Boulevard, 1",
                    "CountryNameCode": "UAE",
                    "CountryName": "Dubai",
                    "AdministrativeArea": {
                      "AdministrativeAreaName": "Dubai",
                      "Locality": {
                        "LocalityName": "Dubai",
                        "Thoroughfare": {
                          "ThoroughfareName": "Mohammed Bin Rashid Boulevard",
                          "Premise": {
                            "PremiseNumber": "1",
                            "PostalCode": {
                              "PostalCodeNumber": "00000"
                            }
                          }
                        }
                      }
                    }
                  }
                }
              }
            },
            "description": "UAE, Dubai",
            "name": "Mohammed Bin Rashid Boulevard, 1",
            "boundedBy": {
              "Envelope": {
                "lowerCorner": "25.196563 55.274149",
                "upperCorner": "25.197612 55.274183"
              }
            },
            "Point": {
              "pos": "25.197300 55.274243"
            }
          }
        }
      ]
    }
  }
}

Response paramsResponse params

response

Geocoder's response.

GeoObjectCollection

Main collection of geo objects.

metaDataProperty

Metadata of the collection of geo objects.

GeocoderResponseMetaData

Information about the request and the number of toponyms found. Inside this object there can be fields:

• fix – a character corrected by the spelling service.
• request – requested address.
• suggest – variant of response corrected by the correction service.
• found – number of toponyms found.
• results – number of requested search results.
• skip – shows how many results to skip in the service response (from the beginning of the list).

featureMember

List of geo objects.

GeoObject

The geo object collection.

metaDataProperty

Geo object metadata.

GeocoderMetaData

Detailed information about the toponym found. There can be fields inside:

• kind – type of toponym found.

  Possible values

  kind	The type of toponym found	The text value (an example)
  house	a detached house	United Arab Emirates, Dubai, Mohammed Bin Rashid Boulevard, 1
  street	street	United Arab Emirates, Dubai, Mohammed Bin Rashid Boulevard
  metro	subway station	United Arab Emirates, Dubai, Rad Line, metro Mashreq
  district	city district	United Arab Emirates, Dubai, Bur Dubai
  locality	locality: city, town, village, etc.	United Arab Emirates, Dubai
  area	regional district (oblast)	United Arab Emirates, Abu Dhabi, Al Ain
  province	oblast, region	United Arab Emirates, Abu Dhabi
  country	country	Türkiye
  hydro	river, lake, stream, reservoir, etc.	United Arab Emirates, Al Qudra
  vegetation	forest, park, orchard, etc.	United Arab Emirates, Dubai, Miracle Garden
  airport	airport	United Arab Emirates, Dubai, Al Maktoum
  other	other	United Arab Emirates, Dubai, Palm Jumeirah Island

• precision – house match precision in request and response.

  Possible values

  precision	The house number in the request	The house number in the response	Comment
  exact	27, unit 1	27c1	A found building has the specified house number.
  number	31, building 4	31/2	A found building has the specified house number, but a different building or unit number.
  near	16/3	18	A found building has a house number close to the requested address.
  range	12	12	Found approximate coordinates of the requested building.
  street	18	–	Only the street was found.
  other	22	–	The street name does not match, but a village, district, etc. matches.

• text – full address of the object in one line of text.

• Address – information about the found object. There can be fields inside:

  • country_code — country code in the format ISO 3166-1.
  • formatted — the address of a toponym in one line.
  • Components — the address of a toponym divided into components. The components are represented by a pair of values kind and name and are organized in descending order from the largest to the smallest (for example, from country to house).

  Warning

  The AddressDetails field is obsolete. The Address field is used instead. It displays the complete address of the object in hierarchical order (country, region, city, district, street, house, building).

name

The text that is recommended to be specified as a title when displaying the found object.

description

The text that is recommended to be specified as a subtitle when displaying the found object.

boundedBy

The boundaries of the area in which the company belongs. Contains the coordinates of the lower left and upper right corners of the area. The coordinates are listed in the sequence "longitude, latitude".

uri

ID of the found object.

Point.pos

Coordinates of the geo object.

Coordinates of the request in the geocoder's responseCoordinates of the request in the geocoder's response

The geocoder returns the given coordinates in the metaDataProperty.GeocoderResponseMetaData.Point.pos field. Coordinates are displayed in the format "[longitude] [latitude]":

{
  "GeocoderResponseMetaData": {
    "request": "E134.854,S25.828",
    "found": "1",
    "results": "10",
    "Point": {
      "pos": "134.854412 -25.828084"
    }
  }
}

Order of resultsOrder of results

• For direct geocoding (the coordinates are determined using the address and/or name), the results are sorted according to their similarity to the address or name specified in the request.
• For reverse geocoding (the address is determined from the coordinates), the results are sorted according to the size of the geometric area that the object belongs to, in reverse order (house number, street, district, city, and so on).

Error messagesError messages

If an error occurs while processing a request, API returns a message with the error description in the message field.

Examples:

{
    "statusCode": 400,
    "error": "Bad Request",
    "message": "Parameter \"geocode\": \"geocode\" is not allowed to be empty"
}

{
    "statusCode": 400,
    "error": "Bad Request",
    "message": "\"Request\" must contain at least one of [geocode, uri]"
}

{
    "statusCode": 400,
    "error": "Bad Request",
    "message": "Missing apikey"
}

{
    "statusCode": 403,
    "error": "Forbidden",
    "message": "Invalid apikey"
}