Response format

Search for geographical features

This section provides an example of a request and the service response when searching for geographical features.

https://geosearch.api.mappable.world/v1/?text=Dubai Marina&type=geo&lang=en_US&apikey=YOUR_API_KEY

The response from the service is shown below (for reverse geocoding, the response format is the same).

Response
{
  "type": "FeatureCollection",
  "properties": {
    "ResponseMetaData": {
      "SearchRequest": {
        "request": "Dubai Marina",
        "results": 10,
        "skip": 0,
        "boundedBy": [
          [
            53.426262,
            23.532086
          ],
          [
            56.114166,
            25.763073
          ]
        ]
      },
      "SearchResponse": {
        "found": 10,
        "Point": {
          "type": "Point",
          "coordinates": [
            54.702308,
            24.478121
          ]
        },
        "boundedBy": [
          [
            55.117113,
            25.064766
          ],
          [
            55.155328,
            25.104558
          ]
        ],
        "display": "single"
      }
    }
  },
  "features": [
    {
      "type": "Feature",
      "properties": {
        "GeocoderMetaData": {
          "kind": "locality",
          "text": "United Arab Emirates, Dubai, Jumeira, Dubai Marina",
          "precision": "other"
        },
        "description": "Jumeira, Dubai, United Arab Emirates",
        "name": "Dubai Marina",
        "boundedBy": [
          [
            55.107187,
            25.047779
          ],
          [
            55.173069,
            25.107781
          ]
        ]
      },
      "geometry": {
        "type": "Point",
        "coordinates": [
          55.13667,
          25.080549
        ]
      }
    }
  ]
}

Warning

We only guarantee support for the fields that are described in the example. We do not recommend using other fields that are found in the response but are not covered in the documentation. Such fields might not be supported in the future.

Response params

type *

Always has the value FeatureCollection. This ensures (partial) compatibility with GeoJSON format.

properties *

Container for metadata describing the request and response.

ResponseMetaData *

Metadata describing the request and response.

SearchRequest *

Metadata describing the request.

request *

Request string.

results

Maximum number of results to be returned.

skip

Number of results to skip.

boundedBy

Boundaries of the area that the objects to search for are presumably located in.

Set as the coordinates of the upper-left and lower-right corners of the area. Coordinates are set in the order "latitude, longitude".

The boundaries of the area are automatically defined by the service.

SearchResponse *

Metadata describing the response.

found *

The number of objects found.

Point *

This element is used for compatibility with GeoJSON format.

type *
Geometry type.
coordinates *
Object coordinates.
boundedBy

Boundaries of the viewport for found objects. Contains the coordinates of the lower-left and upper-right corners of the area. Coordinates are set in the order "longitude, latitude".

display

Recommendations for displaying search results. Possible values:

  • Single: Recommends showing the first found object.
  • Multiple: Recommends showing all found objects.
features *

Container for search results.

type *

Always has the value Feature. This ensures (partial) compatibility with GeoJSON format.

properties *

Metadata describing the found object.

GeocoderMetaData *

Detailed information about the found object.

kind *

Toponym type. List of possible values:

  • house: House.
  • street: Street.
  • Metro: Metro station
  • district: city district
  • locality: Locality (city, town, village, and so on).
text *

The object's full address.

precision *

Precision for matching a found house number to the house number in the query ( Learn more).

description

Text recommended to set as a subtitle when displaying the found object.

name

Text that is recommended to set as the title when displaying the found object.

boundedBy

Boundaries of an area that the business is located in. Contains the coordinates of the lower-left and upper-right corners of the area. Coordinates are set in the order "longitude, latitude".

uri

ID of the found object.

geometry *

Description of the found object's geometry.

type *

Geometry type.

coordinates *
Object coordinates.

Search for businesses

The API returns a list of organizations that best match the query. For example, for the query «pharmacy Dubai», the list of results will not show all pharmacies in the city, but the ones that the API considers the best matches.

https://geosearch.api.mappable.world/v1/?text=Dubai,The Museum of The Future&type=biz&lang=en_US&results=1&apikey=YOUR_API_KEY

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

Response
{
  "type": "FeatureCollection",
  "properties": {
    "ResponseMetaData": {
      "SearchRequest": {
        "request": "Dubai,The Museum of The Future",
        "results": 10,
        "skip": 0,
        "boundedBy": [
          [
            53.426262,
            23.532086
          ],
          [
            56.114166,
            25.763073
          ]
        ]
      },
      "SearchResponse": {
        "found": 1,
        "boundedBy": [
          [
            55.270869,
            25.201209
          ],
          [
            55.292509,
            25.229877
          ]
        ],
        "display": "multiple"
      }
    }
  },
  "features": [
    {
      "type": "Feature",
      "properties": {
        "CompanyMetaData": {
          "id": "171100494916",
          "name": "The Museum of The Future",
          "address": "Dubai, Zaabeel, Trade Center Second",
          "url": "http://museumofthefuture.ae/",
          "Categories": [
            {
              "class": "museum",
              "name": "Museum"
            }
          ],
          "Hours": {
            "Availabilities": [
              {
                "Everyday": true,
                "Intervals": [
                  {
                    "from":"10:00:00",
                    "to":"19:30:00"
                  }
                ]
              }
            ],
            "text": "daily, 10:00 AM–7:30 PM",
          }
        },
        "description": "Dubai, Zaabeel, Trade Center Second",
        "name": "The Museum of The Future"
      },
      "geometry": {
        "type": "Point",
        "coordinates": [
          55.282062,
          25.219302
        ]
      }
    }
  ]
}

Warning

We only guarantee support for the fields that are described in the example. We do not recommend using other fields that are found in the response but are not covered in the documentation. Such fields might not be supported in the future.

Response params

type *

Always has the value FeatureCollection. This ensures (partial) compatibility with GeoJSON format.

properties

Container for metadata describing the request and response.

ResponseMetaData *

Metadata describing the request and response.

SearchRequest *

Metadata describing the request.

request *

Request string.

results

Maximum number of results to be returned.

skip

Number of results to skip.

boundedBy

Boundaries of the area that the objects to search for are presumably located within. Boundaries are set as the coordinates of the upper-left and lower-right corners of the area. Coordinates are set in the order "longitude, latitude".

The boundaries of the area are automatically defined by the service.

SearchResponse *

Metadata describing the response.

found *

The number of objects found.

boundedBy

Boundaries of the viewport for found objects. Contains the coordinates of the lower-left and upper-right corners of the area. Coordinates are set in the order "longitude, latitude".

display

Recommendations for displaying search results. Possible values:

  • single: Recommends showing the first found objects.
  • multiple: Recommends showing all found objects.
features *

Container for search results.

type *

Always has the value Feature. This ensures (partial) compatibility with GeoJSON format.

properties *

Information about the found object.

CompanyMetaData

Contains information about a business: address, contact information, business hours, business type, and so on.

id *

Business ID.

name *

Business name.

address

Business address.

url

Business website.

Categories

List of categories the business belongs to (such as hair salon, hotel, or store).

class
Category class.
name *
Category name.
Phones

List of the business's phone numbers and other contact information.

type
Type of contact information (for example, phone or fax).
formatted *
The full telephone number (or fax) with the country code and area or city code.
Hours

Organization's business hours.

Availabilities

Description of business hours. May contain the fields:

  • Weekdays | Weekend | Everyday | Sunday | Monday...: working days.
  • TwentyFourHours | Intervals: business hours.
Everyday
The business is open every day.
TwentyFourHours
The business is open 24 hours a day.
text *

Business hours described as an arbitrary text.

Features

Features of the organization (for example, accessibility for people with disabilities).

id *

Feature ID. List of possible values:

  • parking_disabled — parking for disabled people;
  • wheelchair_access — wheelchair accessible entrance;
  • automatic_door — automatic door;
  • toilet_for_disabled — toilet for disabled people;
  • call_button — staff call button;
  • elevator_wheelchair_accessible — elevator;
  • ramp — ramp;
  • wheelchair_accessible_vocabulary — wheelchair accessible facility;
  • facilities for disabled people — amenities for people with disabilities;
  • rooms_for_people_with_limited_mobility — rooms for people with limited mobility;
value *

Indicates whether this feature is available in the organization.

type *

The format of the value (for example, enum | text | bool).

name

Name of the feature.

description

Text recommended to set as a subtitle when displaying the found business.

name

Text recommended to set as the title when displaying the found business.

geometry *

Description of the found object's geometry.

type *

Geometry type.

coordinates *

Business coordinates in the order "longitude, latitude".

Error messages

Code Description
400 The request is missing a required parameter or an invalid parameter value is specified. The message contains additional information about the error.
403 The request contains an invalid apikey.
429 There are too many requests in a short time.

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 \"text\": \"text\" is not allowed to be empty"}

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

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

{"statusCode": 403, "error": "Forbidden", "message": "Invalid apikey"}
Previous
Request
Next
Examples