openapi: 3.0.0
info:
  title: "Geo data API"
  version: '1.0'
  description: "Multiple Geo data API. Location by IP address, countries information"
  contact:
    email: geo-data-api@intami.pl
externalDocs:
  description: "API home page"
  url: "https://geo-api.intami.pl/index.html"
servers:
  - url: 'https://geo-data-api.intami.pl'
#  - url: 'http://localhost:8088'
paths:
  '/ip/{IP}':
    parameters:
      - name: "IP"
        required: true
        description: "IP address that you want to resolve data for."
        example: "8.8.8.8"
        in: path
        schema:
          type: string
    get:
      parameters:
        - $ref: "#/components/parameters/Accept"
        - $ref: "#/components/parameters/X-TraceId"
      summary: "Get geo location information about the IP address"
      responses:
        "200":
          description: "IP location information"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/IPLocationResponse"
          headers:
            "X-TraceId":
              $ref: "#/components/headers/X-TraceId"
  '/flag/{countryCode}.webp':
    parameters:
      - name: "countryCode"
        required: true
        description: "ISO2 Country code (two letters)"
        example: "de"
        in: path
        schema:
          type: string
    get:
      parameters:
        - $ref: "#/components/parameters/X-TraceId"
      summary: "WebP image of a country flag"
      responses:
        "200":
          description: "image"
          content:
            image/webp:
              schema:
                type: string
                format: binary
          headers:
            "X-TraceId":
              $ref: "#/components/headers/X-TraceId"
  '/country/{countryCode}':
    parameters:
      - name: "countryCode"
        required: true
        description: "ISO2 Country code (two letters)"
        example: "de"
        in: path
        schema:
          type: string
    get:
      parameters:
        - $ref: "#/components/parameters/X-TraceId"
      summary: "Full information about the country"
      responses:
        "404":
          description: "If country was not found"
        "200":
          description: "Full information about the country"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Country"
          headers:
            "X-TraceId":
              $ref: "#/components/headers/X-TraceId"
  '/city/{cityName}':
    parameters:
      - name: "cityName"
        required: true
        description: "Native name of the city"
        example: "Barcelona"
        in: path
        schema:
          type: string
    get:
      parameters:
        - $ref: "#/components/parameters/X-TraceId"
      summary: "Full information about the country"
      responses:
        "404":
          description: "If city was not found"
        "200":
          description: "Information about the city"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/City"
          headers:
            "X-TraceId":
              $ref: "#/components/headers/X-TraceId"


components:
  schemas:
    IPLocationResponse:
      description: "IP location information"
      type: object
      properties:
        "ip":
          type: string
          description: "Requested IP address"
        "city":
          type: string
          description: "IP address location - city"
        "state":
          type: string
          description: "IP address location - state or province"
        "country":
          description: "Basic country information"
          type: object
          properties:
            name:
              description: "english country name"
              type: string
            nativeName:
              description: "native country name"
              type: string
            codeISO3:
              description: "country code ISO3"
              type: string
            codeISO2:
              description: "country code ISO2"
              type: string
            flagURL:
              description: "country flag URL"
              type: string
            emoji:
              description: "country flag unicode"
              type: string
            continentName:
              description: "country location - continent"
              type: string
        "location":
          type: object
          description: "IP address location - geo location"
    Currency:
      description: "Currency information"
      type: object
      properties:
        code:
          description: "currency international code"
          type: string
        name:
          description: "native name of the currency"
          type: string
        symbol:
          description: "local currency symbol"
          type: string
    TimeZone:
      description: "Time Zone information"
      type: object
      properties:
        "code":
          description: "time zone codename"
          type: string
        "gmtOffset":
          description: "gmt offset in hours"
          type: integer
        "gmtOffsetName":
          description: "gmt offset name"
          type: string
        "abbreviation":
          description: "time zone abbreviation"
          type: string
        "name":
          description: "time zone full name"
          type: string
    Country:
      description: "Country information"
      type: object
      properties:
        numericCode:
          type: string
          description: "country numeric code"
        phoneCode:
          type: string
          description: "phone prefix code"
        capital:
          type: string
          description: "capital city name"
        domain:
          type: string
          description: "domain suffix"
        nationality:
          type: string
          description: "main nationality name"
        currency:
            $ref: "#/components/schemas/Currency"
        region:
          description: "location of the country"
        timezones:
          description: "timezones used in the country"
          type: array
          items:
            $ref: "#/components/schemas/TimeZone"
        translations:
          description: "country name translations"
          type: object
        name:
          description: "country name in english"
          type: string
        nativeName:
          description: "native country name"
          type: string
        codeISO3:
          description: "country code ISO3"
          type: string
        codeISO2:
          description: "country code ISO2"
          type: string
        flagURL:
          description: "country flag URL"
          type: string
        emoji:
          description: "country flag unicode"
          type: string
        emojiU:
          description: "country flag unicode escaped"
          type: string
        continentName:
          description: "country location - continent"
          type: string
    City:
      description: "City information"
      type: object
      properties:
        name:
          type: string
          description: "native name of the coty"
        location:
          $ref: "#/components/schemas/GeoLocation"
        country:
          $ref: "#/components/schemas/Country"
    GeoLocation:
      description: "Geo location information"
      type: object
      properties:
        latitude:
          type: number
        longitude:
          type: number
        altitude:
          type: number

  parameters:
    X-TraceId:
      name: X-TraceId
      required: false
      in: header
      description: "TraceId that is copied to API response header"
      schema:
        type: string
        example: "optional_abc123"
    Accept:
      name: Accept
      in: header
      description: "Requested format of data"
      schema:
        type: string
        enum:
          - "application/json"
          - "application/xml"
        example: "application/json"
        default: "application/json"

  headers:
    X-TraceId:
      required: false
      schema:
        type: string
        example: "abc123"
      description: if request contains X-TraceId header the value will be copied here
