json mapquest openapi

Posted 2021-05-18

{
  "basePath": "/",
  "definitions": {
    "Error": {
      "properties": {
        "error": {
          "description": "A string describing the error that occurred. Note: the precise contents of error messages are subject to change, and thus should not be relied upon programmatically.",
          "type": "string"
        }
      },
      "type": "object"
    },
    "StreetAddress": {
      "properties": {
        "city": {
          "type": "string"
        },
        "countryCode": {
          "type": "string"
        },
        "county": {
          "type": "string"
        },
        "neighborhood": {
          "type": "string"
        },
        "postalCode": {
          "type": "string"
        },
        "stateCode": {
          "type": "string"
        },
        "street": {
          "type": "string"
        },
        "type": {
          "type": "string"
        }
      },
      "required": [
        "countryCode",
        "city",
        "postalCode",
        "street",
        "type"
      ]
    },
    "Feedback": {
      "properties": {
        "resultClickedUrl": {
          "type": "string",
          "description": "Generated URI template to be called when there is an interaction with a SearchResult on a list."
        },
        "resultViewedUrl": {
          "type": "string",
          "description": "Generated URI template to be called when one or more SearchResults are viewed on a list."
        },
        "mapResultClickedUrl": {
          "type": "string",
          "description": "Generated URI template to be called when there is an interaction with a SearchResult on a map."
        },
        "mapResultViewedUrl": {
          "type": "string",
          "description": "Generated URI template to be called when one or more SearchResults are viewed on a map."
        }
      },
      "required": [
        "resultClickedUrl",
        "resultViewedUrl",
        "mapResultClickedUrl",
        "mapResultViewedUrl"
      ]
    },
    "Pagination": {
      "properties": {
        "currentPage": {
          "format": "int32",
          "type": "integer"
        },
        "nextUrl": {
          "description": "A link that will return the next page of results. Link will be absent if there are no more results to show.",
          "type": "string"
        },
        "previousUrl": {
          "description": "A link that will return the previous page of results. Link will be absent on first page of results.",
          "type": "string"
        }
      },
      "required": [
        "currentPage"
      ]
    },
    "PlaceFeature": {
      "properties": {
        "geometry": {
          "description": "A GeoJSON Geometry object representing this object geographically.",
          "type": "object"
        },
        "properties": {
          "$ref": "#/definitions/StreetAddress"
        },
        "type": {
          "description": "The GeoJSON type of this object.",
          "type": "string"
        }
      },
      "required": [
        "properties",
        "geometry",
        "type"
      ]
    },
    "SearchRequest": {
      "properties": {
        "circle": {
          "items": {
            "format": "double",
            "type": "number"
          },
          "type": "array"
        },
        "bbox": {
          "items": {
            "format": "double",
            "type": "number"
          },
          "type": "array"
        },
        "corridor": {
          "items": {
            "items": {
              "format": "double",
              "type": "number"
            },
            "type": "array"
          },
          "type": "array"
        },
        "category": {
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        "pageSize": {
          "format": "int32",
          "type": "integer"
        },
        "page": {
          "format": "int32",
          "type": "integer"
        },
        "location": {
          "items": {
            "format": "double",
            "type": "number"
          },
          "type": "array"
        },
        "q": {
          "type": "string"
        },
        "sort": {
          "type": "string"
        }
      },
      "required": [
        "sort"
      ]
    },
    "SearchResponse": {
      "properties": {
        "feedback": {
          "$ref": "#/definitions/Feedback",
          "description": "An object containing links that relay consumer behavior back to the API."
        },
        "pagination": {
          "$ref": "#/definitions/Pagination",
          "description": "An object that aids in navigation between adjacent pages."
        },
        "request": {
          "$ref": "#/definitions/SearchRequest",
          "description": "An object that contains the input values for the request. Intended to aid in development, by acknowledging and echoing back request parameters; values and structure are subject to change, and thus should not be relied upon programmatically."
        },
        "results": {
          "description": "An object containing a list of matching items.",
          "items": {
            "$ref": "#/definitions/SearchResult"
          },
          "type": "array"
        }
      },
      "required": [
        "pagination",
        "request",
        "results"
      ]
    },
    "SearchResult": {
      "properties": {
        "displayString": {
          "description": "A longer, displayable name for the place, minimally including the name.",
          "type": "string"
        },
        "id": {
          "description": "The internal MapQuest id for the place.",
          "type": "string"
        },
        "language": {
          "description": "The ISO 639-1 language code for the record.",
          "type": "string"
        },
        "name": {
          "description": "A simple name for the place.",
          "type": "string"
        },
        "place": {
          "$ref": "#/definitions/PlaceFeature"
        },
        "slug": {
          "description": "A path fragment for accessing the item on mapquest.com.",
          "type": "string"
        }
      },
      "required": [
        "id",
        "displayString",
        "name",
        "slug",
        "language",
        "place"
      ]
    }
  },
  "host": "www.mapquestapi.com",
  "info": {
    "description": "Place Search is a spatially-aware search engine most commonly used to return Point of Interest (POI) results near a geographic point of reference or within a geographic boundary, such as 'find all coffee shops within the extent of the current map.' Results can be ordered by distance or relevance. This API complements the Search Ahead API by performing the backend search necessary to fulfill category or franchise requests.",
    "title": "MapQuest Search API: Place Search",
    "version": "0.2.0"
  },
  "paths": {
    "/search/v4/place": {
      "get": {
        "description": "Get a list of search results ordered by relevance or distance from a spatial reference point, optionally filtered by category, and optionally bounded within a geographic constraint.",
        "parameters": [
          {
            "description": "A geographic context used for searching, ranking, and ordering results. Must consist of two comma-separated floating-point values: the longitude, latitude; the first coordinate must lie in the range [-180, 180], and the second must lie in the range [-90, 90]. Note: 'sort=distance' requires a location; if bounding with a circle/bbox and no location is specified, the center of the circle/bbox will be used by default.",
            "in": "query",
            "items": {
              "collectionFormat": "csv",
              "format": "double",
              "type": "number"
            },
            "name": "location",
            "required": false,
            "type": "array"
          },
          {
            "description": "The categories of places to search over. Must consist of a comma-separated list of values, specified with 'sic:' followed by the alphanumeric code. Valid codes include any 'sic' values returned by the Search Ahead API, as well as six-digit North American Industry Classification System (NAICS) codes. Required if q is not specified.",
            "in": "query",
            "items": {
              "type": "string"
            },
            "name": "category",
            "required": false,
            "type": "array"
          },
          {
            "description": "The scheme used to order results. Must be 'distance' or 'relevance'. Note: 'sort=distance' requires a location; if bounding with a circle/bbox and no location is specified, the center of the circle/bbox will be used by default. If a location is detected in the 'q' parameter with 'sort=relevance', the location may influence relevance scoring. 'sort=importance' was available as a sorting option in the initial version of the API, but this option has been deprecated in favor of 'sort=relevance'. 'sort=importance' will be unavailable after 3/31/18; API implementers using 'sort=importance' should migrate to 'sort=relevance'.",
            "in": "query",
            "name": "sort",
            "required": true,
            "type": "string"
          },
          {
            "default": false,
            "in": "query",
            "name": "feedback",
            "required": false,
            "type": "boolean"
          },
          {
            "description": "A valid and authorized MapQuest API key.",
            "in": "query",
            "name": "key",
            "required": true,
            "type": "string"
          },
          {
            "description": "A geographic circle used to bound the search. Only places within the bound will be returned in results. Must consist of three comma-separated floating-point values: the longitude and latitude of the circle's center, and the radius in meters; the first coordinate must lie in the range [-180, 180], the second must lie in the range [-90, 90], and the radius must lie in the range [0, 800000]. Note: only one of 'circle' and 'bbox' may be specified.",
            "in": "query",
            "items": {
              "collectionFormat": "csv",
              "format": "double",
              "type": "number"
            },
            "name": "circle",
            "required": false,
            "type": "array"
          },
          {
            "description": "A geographic rectangle used to bound the search. Only places within the bound will be returned in results. Must consist of four comma-separated floating-point values: the longitude and latitude of the lower-left corner followed by the longitude and latitude of the upper-right corner; longitudes must lie in the range [-180, 180], and latitudes must lie in the range [-90, 90]. Note: only one of 'circle' and 'bbox' may be specified.",
            "in": "query",
            "items": {
              "collectionFormat": "csv",
              "format": "double",
              "type": "number"
            },
            "name": "bbox",
            "required": false,
            "type": "array"
          },
          {
            "description": "A collection of points defining a route used for the search. Must consist of two or more arrays of floating-point longitude, latitude values. Longitudes must lie in the range [-180, 180], and latitudes must lie in the range [-90, 90]. Example: [-120.5,10.1],[-119.4,10.3] Note: Corridor cannot be used with 'location' or 'sort=distance'.",
            "in": "query",
            "items": {
              "items": {
                "collectionFormat": "csv",
                "format": "double",
                "type": "number"
              },
              "type": "array"
            },
            "name": "corridor",
            "required": false,
            "type": "array"
          },
          {
            "description": "The number of results to return per page. Must lie in the range [1, 50]. Default if unspecified: 10. Note: the starting result number on the requested page must be between 1 and 500, so the maximum allowed value for 'pageSize' could in practice be less than 50, depending on the value of 'page'.",
            "format": "int32",
            "in": "query",
            "maximum": 50,
            "minimum": 1,
            "name": "pageSize",
            "required": false,
            "type": "integer"
          },
          {
            "description": "(Deprecated.) A synonym for 'pageSize', with the same semantics and constraints. If both 'pageSize' and 'limit' are specified, 'pageSize' takes precedence.",
            "format": "int32",
            "in": "query",
            "maximum": 50,
            "minimum": 1,
            "name": "limit",
            "required": false,
            "type": "integer"
          },
          {
            "description": "The page within the result set to return, where 'pageSize' determines the page size. Must lie in the range [1, 500], and the starting result number on the requested page must be between 1 and 500. Default if unspecified: 1.",
            "format": "int32",
            "in": "query",
            "maximum": 500,
            "minimum": 1,
            "name": "page",
            "required": false,
            "type": "integer"
          },
          {
            "description": "A query phrase. Results returned from the Points of Interest dataset will best match the provided query phrase (string) and location (if provided). Required if a category is not specified. Examples: 'Starbucks, Denver CO' or 'hotels'",
            "in": "query",
            "name": "q",
            "required": false,
            "type": "string"
          }
        ],
        "responses": {
          "200": {
            "description": "An object containing a list of search results, plus an echoed version of the request.",
            "schema": {
              "$ref": "#/definitions/SearchResponse"
            }
          },
          "400": {
            "description": "An error condition, characterized by an appropriate HTTP status code and a descriptive message.",
            "schema": {
              "$ref": "#/definitions/Error"
            }
          },
          "500": {
            "description": "An error condition, characterized by an appropriate HTTP status code and a descriptive message.",
            "schema": {
              "$ref": "#/definitions/Error"
            }
          }
        },
        "summary": "Search for places with optional geographic and categorical contexts.",
        "tags": [
          "place"
        ]
      }
    }
  },
  "produces": [
    "application/json"
  ],
  "swagger": "2.0",
  "tags": [
    {
      "name": "routes"
    },
    {
      "name": "place"
    }
  ]
}