openapi: 3.0.3
info:
    title: Global.health geolocation service
    description: Server for looking up geographic information for Global.health line-list data
    termsOfService: 'https://global.health/terms-of-use/'
    contact:
        name: Global.health
        url: https://global.health
        email: info@global.health
    license:
        name: MIT
        url: 'https://opensource.org/licenses/MIT'
    version: 1.0.0
tags:
    - name: Geocode
      description: Geolocation of a case
    - name: Convert
      description: Converting geocoding-related values
paths:
    /geocode/seed:
        post:
            tags: [Geocode]
            summary: Adds geocodes to the geocoding database
            operationId: seedGeocodes
            requestBody:
                description: A single geocode record
                required: true
                content:
                    application/json:
                        schema:
                            type: object
            responses:
                '200':
                    $ref: '#/components/responses/200'
    /geocode/clear:
        post:
            tags: [Geocode]
            summary: Clears geocodes from the geocoding database
            operationId: clearGeocodes
            responses:
                '200':
                    $ref: '#/components/responses/200'
    /geocode/suggest:
        get:
            tags: [Suggest, Geocode]
            summary: Suggests geocodes for a given query string
            operationId: suggestGeocodes
            parameters:
                - name: q
                  in: query
                  description: The location string for which to find geocodes
                  required: true
                  allowReserved: true
                  schema:
                      type: string
                - name: limitToResolution
                  in: query
                  allowReserved: true
                  schema:
                      type: string
                  description: >
                      Comma-separated list of resolutions to restrict geocoding to.
                      Allowed values are: Point, Admin3, Admin2, Admin1, Country.
            responses:
                '200':
                    $ref: '#/components/responses/200LocationArray'
                '422':
                    $ref: '#/components/responses/422'
                '500':
                    $ref: '#/components/responses/500'
    /geocode/convertUTM:
        get:
            tags: [Convert]
            summary: Convert UTM coordinates to latitude/longitude.
            operationId: convert
            parameters:
                - name: n
                  in: query
                  description: The northing coordinate (UTMY)
                  required: true
                  schema:
                    type: number
                - name: e
                  in: query
                  description: The easting coordinate (UTMX)
                  required: true
                  schema:
                    type: number
                - name: z
                  in: query
                  required: true
                  description: The UTM zone.
                  schema:
                    type: number
            responses:
                '200':
                    $ref: '#/components/responses/200Position'
                '400':
                    $ref: '#/components/responses/400'
                '500':
                    $ref: '#/components/responses/500'
    /geocode/countryName:
        get:
            tags: [Convert]
            summary: Convert ISO-3166-1 2-letter country code to the country's name.
            operationId: countryName
            parameters:
                - name: c
                  in: query
                  required: true
                  description: The ISO-3166-1 country code
                  example: CR
                  schema:
                    type: string
            responses:
                '200':
                    $ref: '#/components/responses/200String'
                '400':
                    $ref: '#/components/responses/400'
                '404':
                    $ref: '#/components/responses/404'
                '500':
                    $ref: '#/components/responses/500'
                    
components:
    schemas:
        Location:
            type: object
            properties:
                query:
                    type: string
                country:
                    type: string
                    description: ISO-3166-2 code of a country
                    minLength: 2
                    maxLength: 2
                    example: CR
                administrativeAreaLevel1:
                    type: string
                administrativeAreaLevel2:
                    type: string
                administrativeAreaLevel3:
                    type: string
                place:
                    type: string
                name:
                    type: string
                geoResolution:
                    type: string
                geometry:
                    $ref: '#/components/schemas/Position'
        LocationArray:
            description: A list of geo locations
            type: array
            items:
                $ref: '#/components/schemas/Location'
        Position:
            type: object
            properties:
                latitude:
                    type: number
                    minimum: -90
                    maximum: 90
                longitude:
                    type: number
                    minimum: -180
                    maximum: 180
            required:
                - latitude
                - longitude
    responses:
        '200LocationArray':
            description: OK
            content:
                application/json:
                    schema:
                        $ref: '#/components/schemas/LocationArray'
        '200Position':
            description: OK
            content:
                application/json:
                    schema:
                        $ref: '#components/schemas/Position'
        '200String':
            description: OK
            content:
                application/json:
                    schema:
                        type: string
        '200':
            description: OK
        '400':
            description: Malformed request
        '403':
            description: Forbidden
        '404':
            description: Not found
        '422':
            description: Unprocessable entity
        '500':
            description: Internal server error
servers:
    - url: http://localhost:8080/
      description: Local server