openapi: 3.0.0
info:
  title: ipapi
  description: ipapi offers a powerful, real-time IP to geolocation API capable of looking up accurate location data and assessing
    security threats originating from risky IP addresses. Results are delivered within milliseconds in JSON or XML format.
  version: 1.0.0
servers:
- url: https://api.ipapi.com/api
paths:
  /{IPAddress}:
    get:
      tags:
      - Endpoints
      summary: ipapi :- Standard & Bulk IP Lookup
      description: The ipapi primary endpoint looks up IPv4/IPv6 addresses. Attach a single IP address to the base URL for
        a Standard Lookup, or a comma-separated list of up to 50 addresses for a Bulk Lookup. Domain URLs are also accepted
        and resolved to the underlying IP address.
      operationId: ipapiIPLookup
      parameters:
      - name: IPAddress
        in: path
        description: A single IPv4/IPv6 address (Standard Lookup) or a comma-separated list of up to 50 addresses (Bulk Lookup).
          Domain URLs are also accepted.
        required: true
        schema:
          type: string
          example: 134.201.250.155
      - name: access_key
        in: query
        description: Your API Access Key.
        required: true
        schema:
          type: string
      - name: callback
        in: query
        description: Specify a JSONP callback function name according to the JSONP Callbacks section.
        required: false
        schema:
          type: string
      - name: fields
        in: query
        description: Set to your preferred output field(s) according to the Specify Output Fields section.
        required: false
        schema:
          type: string
      - name: hostname
        in: query
        description: Set to 1 to enable Hostname Lookup.
        required: false
        schema:
          type: integer
          format: int32
          enum:
          - 0
          - 1
          example: 1
      - name: security
        in: query
        description: Set to 1 to enable the Security module.
        required: false
        schema:
          type: integer
          format: int32
          enum:
          - 0
          - 1
          example: 1
      - name: language
        in: query
        description: Set to a 2-letter language code according to the Specify Output Language section to change output language.
        required: false
        schema:
          type: string
          example: en
      - name: output
        in: query
        description: Set to json or xml to choose between output formats.
        required: false
        schema:
          type: string
          enum:
          - json
          - xml
          example: json
      responses:
        '200':
          description: Geolocation data. A single IP returns one result object; a comma-separated (bulk) request returns an
            array of result objects.
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/IpLookupResponse'
                - type: array
                  items:
                    $ref: '#/components/schemas/IpLookupResponse'
              examples:
                single:
                  summary: Standard single-IP JSON response
                  value:
                    ip: 161.185.160.93
                    type: ipv4
                    continent_code: NA
                    continent_name: North America
                    country_code: US
                    country_name: United States
                    region_code: NY
                    region_name: New York
                    city: Bath Beach
                    zip: '11201'
                    latitude: 40.69459915161133
                    longitude: -73.99063873291016
                    msa: '35620'
                    dma: '501'
                    radius: 30.012950897216797
                    ip_routing_type: fixed
                    connection_type: tx
                    hostname: 161.185.160.93
                    location:
                      geoname_id: 5110302
                      capital: Washington D.C.
                      languages:
                      - code: en
                        name: English
                        native: English
                      country_flag: https://assets.ipapi.com/images/assets/flags_svg/us.svg
                      country_flag_emoji: "ð\x9F\x87ºð\x9F\x87¸"
                      country_flag_emoji_unicode: U+1F1FA U+1F1F8
                      calling_code: '1'
                      is_eu: false
                    time_zone:
                      id: America/New_York
                      current_time: '2024-06-14T00:26:20-04:00'
                      gmt_offset: -14400
                      code: EDT
                      is_daylight_saving: true
                    currency:
                      code: USD
                      name: US Dollar
                      plural: US dollars
                      symbol: $
                      symbol_native: $
                    connection:
                      asn: 22252
                      isp: The City of New York
                      sld: nyc
                      tld: gov
                      carrier: the city of new york
                      home: false
                      organization_type: Government (Municipal)
                      isic_code: O8411
                      naics_code: 009211
                    security:
                      is_proxy: false
                      proxy_type: null
                      is_crawler: false
                      crawler_name: null
                      crawler_type: null
                      is_tor: false
                      threat_level: low
                      threat_types: null
                      proxy_last_detected: null
                      proxy_level: null
                      vpn_service: null
                      anonymizer_status: null
                      hosting_facility: false
        '400':
          description: Malformed request or invalid parameters (e.g. invalid_fields).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: Too many IP addresses provided in a single bulk request (too_many_ips).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
        '429':
          $ref: '#/components/responses/429'
        '500':
          $ref: '#/components/responses/500'
        '503':
          $ref: '#/components/responses/503'
  /check:
    get:
      tags:
      - Endpoints
      summary: ipapi :- /check (Requester IP Lookup)
      description: The ipapi API also offers a separate API endpoint capable of detecting the IP address which the current
        API request is coming from. In order to use this endpoint, simply append check to the API's base URL and specify your
        preferred optional parameters.
      operationId: ipapiCheckRequesterIPLookup
      parameters:
      - name: access_key
        in: query
        description: Your API Access Key.
        required: true
        schema:
          type: string
      - name: callback
        in: query
        description: Specify a JSONP callback function name according to the JSONP Callbacks section.
        required: false
        schema:
          type: string
      - name: fields
        in: query
        description: Set to your preferred output field(s) according to the Specify Output Fields section.
        required: false
        schema:
          type: string
      - name: hostname
        in: query
        description: Set to 1 to enable Hostname Lookup.
        required: false
        schema:
          type: integer
          format: int32
          enum:
          - 0
          - 1
          example: 1
      - name: security
        in: query
        description: Set to 1 to enable the Security module.
        required: false
        schema:
          type: integer
          format: int32
          enum:
          - 0
          - 1
          example: 1
      - name: language
        in: query
        description: Set to a 2-letter language code according to the Specify Output Language section to change output language.
        required: false
        schema:
          type: string
          example: en
      - name: output
        in: query
        description: Set to json or xml to choose between output formats.
        required: false
        schema:
          type: string
          enum:
          - json
          - xml
          example: json
      responses:
        '200':
          description: Geolocation data for the IP address the request originated from.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IpLookupResponse'
              examples:
                single:
                  summary: Standard single-IP JSON response
                  value:
                    ip: 161.185.160.93
                    type: ipv4
                    continent_code: NA
                    continent_name: North America
                    country_code: US
                    country_name: United States
                    region_code: NY
                    region_name: New York
                    city: Bath Beach
                    zip: '11201'
                    latitude: 40.69459915161133
                    longitude: -73.99063873291016
                    msa: '35620'
                    dma: '501'
                    radius: 30.012950897216797
                    ip_routing_type: fixed
                    connection_type: tx
                    hostname: 161.185.160.93
                    location:
                      geoname_id: 5110302
                      capital: Washington D.C.
                      languages:
                      - code: en
                        name: English
                        native: English
                      country_flag: https://assets.ipapi.com/images/assets/flags_svg/us.svg
                      country_flag_emoji: "ð\x9F\x87ºð\x9F\x87¸"
                      country_flag_emoji_unicode: U+1F1FA U+1F1F8
                      calling_code: '1'
                      is_eu: false
                    time_zone:
                      id: America/New_York
                      current_time: '2024-06-14T00:26:20-04:00'
                      gmt_offset: -14400
                      code: EDT
                      is_daylight_saving: true
                    currency:
                      code: USD
                      name: US Dollar
                      plural: US dollars
                      symbol: $
                      symbol_native: $
                    connection:
                      asn: 22252
                      isp: The City of New York
                      sld: nyc
                      tld: gov
                      carrier: the city of new york
                      home: false
                      organization_type: Government (Municipal)
                      isic_code: O8411
                      naics_code: 009211
                    security:
                      is_proxy: false
                      proxy_type: null
                      is_crawler: false
                      crawler_name: null
                      crawler_type: null
                      is_tor: false
                      threat_level: low
                      threat_types: null
                      proxy_last_detected: null
                      proxy_level: null
                      vpn_service: null
                      anonymizer_status: null
                      hosting_facility: false
        '400':
          description: Malformed request or invalid parameters (e.g. invalid_fields).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
        '429':
          $ref: '#/components/responses/429'
        '500':
          $ref: '#/components/responses/500'
        '503':
          $ref: '#/components/responses/503'
components:
  schemas:
    IpLookupResponse:
      title: IpLookupResponse
      description: Geolocation and metadata for a single IP address. The location, time_zone, currency, connection and security
        sub-objects depend on the plan and the enabled modules (hostname/security).
      properties:
        ip:
          type: string
          example: 134.201.250.155
        hostname:
          nullable: true
          description: Present when hostname=1.
          type: string
        type:
          type: string
          example: ipv4
        continent_code:
          type: string
          example: NA
        continent_name:
          type: string
          example: North America
        country_code:
          type: string
          example: US
        country_name:
          type: string
          example: United States
        region_code:
          nullable: true
          type: string
          example: CA
        region_name:
          nullable: true
          type: string
          example: California
        city:
          nullable: true
          type: string
          example: Los Angeles
        zip:
          nullable: true
          type: string
          example: '90013'
        latitude:
          nullable: true
          type: number
          format: double
          example: 34.0655
        longitude:
          nullable: true
          type: number
          format: double
          example: -118.2405
        msa:
          nullable: true
          type: string
        dma:
          nullable: true
          type: string
        radius:
          nullable: true
          type: number
        ip_routing_type:
          nullable: true
          type: string
        connection_type:
          nullable: true
          type: string
        location:
          nullable: true
          description: Country and locality metadata.
          properties:
            geoname_id:
              nullable: true
              type: integer
            capital:
              nullable: true
              type: string
              example: Washington D.C.
            languages:
              type: array
              items:
                properties:
                  code:
                    type: string
                    example: en
                  name:
                    type: string
                    example: English
                  native:
                    type: string
                    example: English
                type: object
            country_flag:
              nullable: true
              type: string
              format: uri
            country_flag_emoji:
              nullable: true
              type: string
            country_flag_emoji_unicode:
              nullable: true
              type: string
            calling_code:
              nullable: true
              type: string
              example: '1'
            is_eu:
              nullable: true
              type: boolean
          type: object
        time_zone:
          nullable: true
          description: Time zone metadata.
          properties:
            id:
              type: string
              example: America/Los_Angeles
            current_time:
              type: string
              format: date-time
            gmt_offset:
              type: integer
            code:
              type: string
              example: PDT
            is_daylight_saving:
              type: boolean
          type: object
        currency:
          nullable: true
          description: Currency metadata for the country.
          properties:
            code:
              type: string
              example: USD
            name:
              type: string
              example: US Dollar
            plural:
              type: string
              example: US dollars
            symbol:
              type: string
              example: $
            symbol_native:
              type: string
              example: $
          type: object
        connection:
          nullable: true
          description: Network and ISP data.
          properties:
            asn:
              nullable: true
              type: integer
            isp:
              nullable: true
              type: string
            sld:
              nullable: true
              type: string
            tld:
              nullable: true
              type: string
            carrier:
              nullable: true
              type: string
            home:
              nullable: true
              type: boolean
            organization_type:
              nullable: true
              type: string
            isic_code:
              nullable: true
              type: string
            naics_code:
              nullable: true
              type: string
          type: object
        security:
          nullable: true
          description: Security assessment (present when security=1 and the plan supports it).
          properties:
            is_proxy:
              nullable: true
              type: boolean
            proxy_type:
              nullable: true
              type: string
            is_crawler:
              nullable: true
              type: boolean
            crawler_name:
              nullable: true
              type: string
            crawler_type:
              nullable: true
              type: string
            is_tor:
              nullable: true
              type: boolean
            threat_level:
              nullable: true
              type: string
              example: low
            threat_types:
              nullable: true
              type: array
              items:
                type: string
            proxy_last_detected:
              nullable: true
              type: string
            proxy_level:
              nullable: true
              type: string
            vpn_service:
              nullable: true
              type: string
            anonymizer_status:
              nullable: true
              type: string
            hosting_facility:
              nullable: true
              type: boolean
          type: object
      type: object
      example:
        ip: 161.185.160.93
        type: ipv4
        continent_code: NA
        continent_name: North America
        country_code: US
        country_name: United States
        region_code: NY
        region_name: New York
        city: Bath Beach
        zip: '11201'
        latitude: 40.69459915161133
        longitude: -73.99063873291016
        msa: '35620'
        dma: '501'
        radius: 30.012950897216797
        ip_routing_type: fixed
        connection_type: tx
        hostname: 161.185.160.93
        location:
          geoname_id: 5110302
          capital: Washington D.C.
          languages:
          - code: en
            name: English
            native: English
          country_flag: https://assets.ipapi.com/images/assets/flags_svg/us.svg
          country_flag_emoji: 🇺🇸
          country_flag_emoji_unicode: U+1F1FA U+1F1F8
          calling_code: '1'
          is_eu: false
        time_zone:
          id: America/New_York
          current_time: '2024-06-14T00:26:20-04:00'
          gmt_offset: -14400
          code: EDT
          is_daylight_saving: true
        currency:
          code: USD
          name: US Dollar
          plural: US dollars
          symbol: $
          symbol_native: $
        connection:
          asn: 22252
          isp: The City of New York
          sld: nyc
          tld: gov
          carrier: the city of new york
          home: false
          organization_type: Government (Municipal)
          isic_code: O8411
          naics_code: 009211
        security:
          is_proxy: false
          proxy_type: null
          is_crawler: false
          crawler_name: null
          crawler_type: null
          is_tor: false
          threat_level: low
          threat_types: null
          proxy_last_detected: null
          proxy_level: null
          vpn_service: null
          anonymizer_status: null
          hosting_facility: false
    Error:
      title: Error
      type: object
      required:
      - success
      - error
      properties:
        success:
          type: boolean
          example: false
        error:
          type: object
          properties:
            code:
              type: integer
              example: 101
            type:
              type: string
              example: invalid_access_key
            info:
              type: string
              example: 'You have not supplied a valid API Access Key. [Technical Support: support@apilayer.com]'
  responses:
    '401':
      description: Unauthorized
      content:
        application/json; Charset=UTF-8:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            account_on_hold:
              summary: account_on_hold
              value:
                success: false
                error:
                  code: 107
                  type: account_on_hold
                  info: 'Your account currently has open invoices and API has been automatically disabled. Please settle your
                    open balance or downgrade to the Free Plan to restore API access. [Support: support@apilayer.com]'
            invalid_access_key:
              summary: invalid_access_key
              value:
                success: false
                error:
                  code: 101
                  type: invalid_access_key
                  info: 'You have not supplied a valid API Access Key. [Technical Support: support@apilayer.com]'
            missing_access_key:
              summary: missing_access_key
              value:
                success: false
                error:
                  code: 101
                  type: missing_access_key
                  info: 'You have not supplied an API Access Key. [Required format: access_key=YOUR_ACCESS_KEY]'
            inactive_user:
              summary: inactive_user
              value:
                success: false
                error:
                  code: 102
                  type: inactive_user
                  info: Permission denied - User not active.
    '403':
      description: Forbidden
      content:
        application/json; Charset=UTF-8:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            https_access_restricted:
              summary: https_access_restricted
              value:
                success: false
                error:
                  code: 105
                  type: https_access_restricted
                  info: Access Restricted - Your current Subscription Plan does not support HTTPS Encryption.
            function_access_restricted:
              summary: function_access_restricted
              value:
                success: false
                error:
                  code: 105
                  type: function_access_restricted
                  info: Access Restricted - Your current Subscription Plan does not support this API Function.
            api_access_blocked:
              summary: api_access_blocked
              value:
                success: false
                error:
                  code: 104
                  type: api_access_blocked
                  info: Your API access has been temporarily disabled. Please upgrade your Subscription Plan or contact support.
    '404':
      description: Not Found
      content:
        application/json; Charset=UTF-8:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            invalid_api_function:
              summary: invalid_api_function
              value:
                success: false
                error:
                  code: 103
                  type: invalid_api_function
                  info: This API Function does not exist.
            404_not_found:
              summary: 404_not_found
              value:
                success: false
                error:
                  code: 404
                  type: 404_not_found
                  info: 404 - The requested resource could not be found. Please try again or contact support.
    '429':
      description: Too Many Requests
      content:
        application/json; Charset=UTF-8:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            usage_limit_reached:
              summary: usage_limit_reached
              value:
                success: false
                error:
                  code: 104
                  type: usage_limit_reached
                  info: Your monthly usage limit has been reached. Please upgrade your Subscription Plan.
            daily_usage_limit_reached:
              summary: daily_usage_limit_reached
              value:
                success: false
                error:
                  code: 104
                  type: daily_usage_limit_reached
                  info: Your daily usage limit has been reached. Please try again tomorrow or upgrade your subscription plan.
            fair_use_limit_reached:
              summary: fair_use_limit_reached
              value:
                success: false
                error:
                  code: 104
                  type: fair_use_limit_reached
                  info: 'Your fair use limit has been reached. [Please contact support: support@apilayer.com]'
            rate_limit_reached:
              summary: rate_limit_reached
              value:
                success: false
                error:
                  code: 106
                  type: rate_limit_reached
                  info: 'You have exceeded the maximum rate limitation allowed on your subscription plan. Please refer to
                    the "Rate Limits" section of the API Documentation for details. '
    '500':
      description: Internal Server Error
      content:
        application/json; Charset=UTF-8:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            internal_error:
              summary: internal_error
              value:
                success: false
                error:
                  code: 0
                  type: internal_error
                  info: 'An error has occured. [Technical Support: support@apilayer.com]'
    '503':
      description: Service Unavailable
      content:
        application/json; Charset=UTF-8:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            maintenance_mode:
              summary: maintenance_mode
              value:
                success: false
                error:
                  code: 503
                  type: maintenance_mode
                  info: ''
externalDocs:
  description: ipapi official documentation (reference)
  url: https://ipapi.com/documentation