{
  "openapi": "3.1.0",
  "info": {
    "title": "what4words API",
    "version": "1.0.0",
    "description": "Convert GPS coordinates into four common words and back, using the FixPhrase algorithm (© 2021 Netsyms Technologies, BSD-3-Clause). Words work in any order. No authentication required.",
    "contact": {
      "name": "José Luis Saorín",
      "url": "https://joseluissaorin.com"
    },
    "license": {
      "name": "BSD-3-Clause (algorithm)",
      "url": "https://what4words.joseluissaorin.com/license"
    }
  },
  "servers": [
    {
      "url": "https://what4words.joseluissaorin.com"
    }
  ],
  "paths": {
    "/api/encode": {
      "get": {
        "operationId": "encodeCoordinates",
        "summary": "Coordinates → four words",
        "parameters": [
          {
            "name": "lat",
            "in": "query",
            "required": true,
            "schema": {
              "type": "number",
              "minimum": -90,
              "maximum": 90
            }
          },
          {
            "name": "lon",
            "in": "query",
            "required": true,
            "schema": {
              "type": "number",
              "minimum": -180,
              "maximum": 180
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Encoded phrase with map links",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/LocationResult"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/api/decode": {
      "get": {
        "operationId": "decodePhrase",
        "summary": "Words → coordinates",
        "parameters": [
          {
            "name": "phrase",
            "in": "query",
            "required": true,
            "description": "2–4 words separated by spaces, dots, dashes, commas or plus signs. Order-insensitive. 4 words = ±11 m, 3 = ±1.1 km, 2 = ±11 km.",
            "schema": {
              "type": "string",
              "examples": [
                "corner.gulp.security.valley"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Decoded location with map links",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/LocationResult"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/api/links": {
      "get": {
        "operationId": "getMapLinks",
        "summary": "Deep links to 19 map apps/services",
        "parameters": [
          {
            "name": "phrase",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "lat",
            "in": "query",
            "required": false,
            "schema": {
              "type": "number"
            }
          },
          {
            "name": "lon",
            "in": "query",
            "required": false,
            "schema": {
              "type": "number"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Map links keyed by service id, each with optional view/directions URLs"
          },
          "400": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/api/gpx": {
      "get": {
        "operationId": "getGpxWaypoint",
        "summary": "GPX waypoint file for coordinates",
        "parameters": [
          {
            "name": "lat",
            "in": "query",
            "required": true,
            "schema": {
              "type": "number"
            }
          },
          {
            "name": "lon",
            "in": "query",
            "required": true,
            "schema": {
              "type": "number"
            }
          },
          {
            "name": "name",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "GPX file",
            "content": {
              "application/gpx+xml": {}
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "LocationResult": {
        "type": "object",
        "properties": {
          "phrase": {
            "type": "string"
          },
          "words": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "latitude": {
            "type": "number"
          },
          "longitude": {
            "type": "number"
          },
          "accuracyDegrees": {
            "type": "number"
          },
          "accuracyMeters": {
            "type": "number"
          },
          "url": {
            "type": "string",
            "format": "uri"
          },
          "maps": {
            "type": "object",
            "description": "Deep links keyed by service id; each has name and view and/or directions URLs"
          },
          "attribution": {
            "type": "string"
          }
        },
        "required": [
          "phrase",
          "words",
          "latitude",
          "longitude"
        ]
      }
    },
    "responses": {
      "Error": {
        "description": "Bad input",
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "properties": {
                "error": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    }
  }
}