api-ninjas-com IP Lookup API

openapi: 3.2.0
info:
  title: Ninjas IP Lookup API
  description: 'Combined OpenAPI specification for every API Ninjas endpoint. Requests go to https://api.api-ninjas.com with an `X-Api-Key` header; get a free key at https://api-ninjas.com/register. Human-readable docs: https://api-ninjas.com/api. Index for LLMs: https://api-ninjas.com/llms.txt.'
  version: 1.0.0
  contact:
    name: API Ninjas
    url: https://api-ninjas.com
  license:
    name: Proprietary
servers:
- url: https://api.api-ninjas.com
  description: API Ninjas Production
security:
- ApiKeyAuth: []
tags:
- name: IP Lookup
  description: The IP Lookup API provides location information for any valid IP address. It works with both IPv4 and IPv6 addresses.
paths:
  /v1/iplookup:
    get:
      tags:
      - IP Lookup
      summary: Get location information for an IP address
      description: Returns location information for an IP address. Requires an `address` in IPv4 form such as 73.9.149.180 or in IPv6 form.
      operationId: getIPInfo
      parameters:
      - name: address
        in: query
        description: IP Address to query. Must be in IPv4 format A.B.C.D (e.g., 73.9.149.180) or IPv6 format X:X:X:X:X:X:X:X (e.g., 2001:0db8:85a3:0000:0000:8a2e:0370:7334).
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Successful response with IP address location information
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IPResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IpLookupOpenapi_ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IpLookupOpenapi_ErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IpLookupOpenapi_ErrorResponse'
      security:
      - ApiKeyAuth: []
components:
  schemas:
    IpLookupOpenapi_ErrorResponse:
      type: object
      properties:
        message:
          type: string
          description: Error message describing the failure
    IPResponse:
      type: object
      properties:
        is_valid:
          type: boolean
          description: The validity status of the IP address
        country:
          type: string
          description: The name of the country where the IP address is located
        country_code:
          type: string
          description: The 2-letter country code of the IP address location
        region_code:
          type: string
          description: The region code of the IP address location. In the United States, this is equivalent to the 2-letter state abbreviation.
        region:
          type: string
          description: The region name where the IP address is located. In the United States, this is equivalent to the state.
        city:
          type: string
          description: The city where the IP address is located
        zip:
          type: string
          description: The ZIP code of the IP address location
        lat:
          type: number
          format: float
          description: The latitude coordinate of the IP address location
        lon:
          type: number
          format: float
          description: The longitude coordinate of the IP address location
        timezone:
          type: string
          description: The time zone related to the IP address
        isp:
          type: string
          description: The Internet Service Provider associated with the IP address
        address:
          type: string
          description: The IP address of the query
        is_datacenter:
          type: boolean
          description: Premium only. Whether the IP belongs to a known cloud or datacenter provider (e.g. AWS, GCP, Azure, Oracle, DigitalOcean).
        is_hosting:
          type: boolean
          description: Premium only. Whether the IP's network (ASN) is a known hosting/datacenter provider.
        is_tor:
          type: boolean
          description: Premium only. Whether the IP is a known Tor exit node.
        is_vpn:
          type: boolean
          description: Premium only. Whether the IP is associated with a known commercial VPN provider.
        is_icloud_relay:
          type: boolean
          description: Premium only. Whether the IP is an Apple iCloud Private Relay egress node.
        is_bogon:
          type: boolean
          description: Premium only. Whether the IP is a bogon (unallocated or reserved address that should not appear on the public internet).
        is_abuser:
          type: boolean
          description: Premium only. Whether the IP appears on multiple public abuse/threat blocklists.
        threat_level:
          type: string
          description: 'Premium only. Overall risk level derived from blocklist activity: one of low, medium, or high.'
        asn:
          type: string
          description: Premium only. The Autonomous System Number that announces the IP (e.g. AS15169).
        asn_name:
          type: string
          description: Premium only. The name of the organization that operates the ASN.
        route:
          type: string
          description: Premium only. The network route (CIDR prefix) the IP belongs to.
        abuse_email:
          type: string
          description: Premium only. The registered abuse-contact email for the IP's network.
        is_eu:
          type:
          - boolean
          - 'null'
          description: 'Whether the country is an EU member state. Premium field: the Free tier receives a notice string in place of the value.'
        is_eea:
          type:
          - boolean
          - 'null'
          description: 'Whether the country is in the European Economic Area (the EU plus Iceland, Liechtenstein and Norway). Premium field: the Free tier receives a notice string in place of the value.'
        languages:
          type:
          - string
          - 'null'
          description: 'Comma-separated BCP-47 language tags commonly used in the country. Premium field: the Free tier receives a notice string in place of the value.'
        urbanisation:
          type:
          - string
          - 'null'
          description: 'Degree of urbanisation at the coordinates: URBAN_CENTRE, DENSE_URBAN_CLUSTER, SEMI_DENSE_URBAN, SUBURBAN, RURAL_CLUSTER, LOW_DENSITY_RURAL, VERY_LOW_DENSITY_RURAL or WATER. Premium field: the Free tier receives a notice string in place of the value.'
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-Api-Key
externalDocs:
  description: API Ninjas documentation
  url: https://api-ninjas.com/api