{
  "swagger": "2.0",
  "info": {
    "title": "Stopfinder API",
    "description": "API for finding public transport stops",
    "version": "1.0.1"
  },
  "host": "api.geops.io",
  "schemes": ["https"],
  "securityDefinitions": {
    "QueryTokenAuth": { "type": "apiKey", "in": "query", "name": "key" },
    "HeaderTokenAuth": {
      "type": "apiKey",
      "in": "header",
      "name": "Authorization"
    }
  },
  "basePath": "/stops/v1",
  "paths": {
    "/": {
      "get": {
        "description": "Returns a stop (or multiple) as GeoJSON FeatureCollection",
        "security": [{ "QueryTokenAuth": [] }, { "HeaderTokenAuth": [] }],
        "produces": ["application/geo+json"],
        "parameters": [
          {
            "in": "query",
            "type": "number",
            "name": "limit",
            "required": false,
            "description": "Control how many matches will be returned"
          },
          {
            "in": "query",
            "name": "q",
            "type": "string",
            "required": true,
            "description": "Anything you'd like to search for"
          },
          {
            "in": "query",
            "name": "prefagencies",
            "type": "string",
            "required": false,
            "description": "comma seperated list, order chooses which agency will be preferred\nas ident_source (for id and code fields)\n",
            "enum": ["sbb", "db"]
          },
          {
            "in": "query",
            "name": "mots",
            "type": "string",
            "required": false,
            "description": "comma seperated list of mot's which should be available\nat the stop\n",
            "enum": [
              "bus",
              "ferry",
              "gondola",
              "tram",
              "rail",
              "funicular",
              "cable_car",
              "subway"
            ]
          },
          {
            "in": "query",
            "name": "bbox",
            "type": "string",
            "description": "left,bottom,right,up coordinates in WGS84 wherein the\nstation should lie\n"
          },
          {
            "in": "query",
            "name": "field",
            "type": "string",
            "description": "which field to look up, default: all of them",
            "enum": ["id", "name", "coords"]
          },
          {
            "in": "query",
            "name": "ref_location",
            "type": "string",
            "description": "Coordinates in WGS84 (in lat,lon order) used to rank stops close to\nthis position higher\n"
          }
        ],
        "responses": {
          "200": {
            "description": "stop(s)",
            "schema": {
              "type": "object",
              "properties": {
                "type": { "type": "string", "enum": ["FeatureCollection"] },
                "features": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "type": { "type": "string", "enum": ["Feature"] },
                      "properties": {
                        "type": "object",
                        "properties": {
                          "uid": {
                            "type": "string",
                            "description": "internal ID"
                          },
                          "name": {
                            "type": "string",
                            "description": "name of the stop",
                            "example": "Bern"
                          },
                          "country_code": {
                            "type": "string",
                            "description": "2 letter country code where the station is located",
                            "example": "CH"
                          },
                          "rank": {
                            "type": "number",
                            "description": "how well the result matches your query, 0\nmeans best\n",
                            "minimum": 0,
                            "maximum": 1
                          },
                          "translated_names": {
                            "description": "array of translations of the stopname",
                            "type": "array",
                            "default": [],
                            "items": {
                              "type": "object",
                              "properties": {
                                "value": { "type": "string" },
                                "language": {
                                  "type": "string",
                                  "enum": ["de", "en", "fr", "it"]
                                }
                              }
                            }
                          },
                          "mot": {
                            "type": "object",
                            "description": "Means of transport that are available at this station",
                            "properties": {
                              "bus": { "type": "boolean" },
                              "ferry": { "type": "boolean" },
                              "gondola": { "type": "boolean" },
                              "tram": { "type": "boolean" },
                              "rail": { "type": "boolean" },
                              "funicular": { "type": "boolean" },
                              "cable_car": { "type": "boolean" },
                              "subway": { "type": "boolean" }
                            }
                          },
                          "ident_source": {
                            "type": "string",
                            "description": "source agency for id and code (see below)",
                            "example": "sbb"
                          },
                          "id": {
                            "type": "string",
                            "description": "uic number",
                            "example": 8507000
                          },
                          "code": {
                            "type": "string",
                            "description": "Abbreviation code from the transport agency (e.g. DS100 for Deutsche Bahn)\n",
                            "example": "BN"
                          },
                          "ifopt": {
                            "type": "string",
                            "description": "ifopt identifier, if available"
                          }
                        }
                      },
                      "geometry": {
                        "type": "object",
                        "description": "the coordinates of the stop",
                        "properties": {
                          "type": { "type": "string", "enum": ["Point"] },
                          "coordinates": {
                            "type": "array",
                            "items": { "type": "number" },
                            "example": [7.439119, 46.94882]
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "limit parameter too high",
            "schema": {
              "type": "object",
              "properties": {
                "error": {
                  "type": "string",
                  "enum": [
                    "400 Bad Request: Limit has to be an integer between 1 and 500"
                  ]
                }
              }
            }
          }
        }
      }
    }
  }
}