HProxy IP location and ASN API

openapi: 3.2.0
info:
  title: HProxy IP location and ASN API
  version: 1.0.0
  description: 'Buy and manage proxies from a prepaid wallet, run the Scraper API, or use the free no-key APIs: a live proxy list, a proxy checker and an IP lookup. JSON in, JSON out. Money is always integer cents (120 = $1.20), never floats.'
  contact:
    url: https://hproxy.com/contact
  license:
    name: Proprietary
servers:
- url: https://hproxy.com
  description: Production
security:
- ApiKeyAuth: []
tags:
- name: IP location and ASN API
paths:
  /api/ip/{ip}:
    get:
      operationId: ip-lookup
      summary: Location and network for any IP
      description: 'One GET returns where an IP is and which network runs it: country, region, city, coordinates, timezone, ASN, ASN organization and ISP. No key, no signup, CORS enabled so you can call it straight from a browser or an extension.


        This is the same lookup that powers the free proxy list and our own proxy checker, so if you are writing a proxy checker of your own, you can label your results with exactly the data we label ours with. It is read from offline databases, so there is no third-party API in the path.


        Two limits apply per IP, and they are deliberately separate. **Requests** on this single-address door are capped at 900 in a burst, refilling 30 per second. **Addresses** are capped by the budget described under the batch endpoint below, and both doors draw on that same budget, so a hundred thousand single lookups cost exactly what one batch of a hundred thousand costs. Every answer reports the address budget in `X-RateLimit-Limit`, `X-RateLimit-Remaining` and `X-RateLimit-Cost`, so you can pace yourself from the headers rather than discovering the limit by being refused. Past either one you get a clean `429` with `Retry-After`.


        Responses carry `Cache-Control: public, max-age=21600`: an address''s location and ASN move on the order of weeks, so cache them hard rather than re-asking on every run.'
      tags:
      - IP location and ASN API
      parameters:
      - name: ip
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
              example:
                ip: 45.79.12.44
                country: US
                country_name: United States
                region: Texas
                city: Dallas
                latitude: 32.7797
                longitude: -96.8022
                timezone: America/Chicago
                asn: 63949
                asn_org: Akamai Technologies, Inc.
                isp: Akamai Technologies, Inc.
                is_datacenter: false
        '400':
          description: Invalid input. The body names the field and the accepted set.
        '401':
          description: Missing or invalid API key.
        '429':
          description: Rate limited. Retry after the delay in the response.
      security: []
  /api/ip:
    post:
      operationId: ip-lookup-batch
      summary: 'Batch: up to 100 000 addresses per call'
      description: 'If you are labeling a whole proxy list, use this instead of one request per proxy. Send up to **100,000** addresses in one call and get one result per address, **in the same order you sent them**, so you can zip the two lists together without matching on anything.


        **You are charged per distinct address, not per request and not per line.** Duplicates are free, because they are free for us: a list that repeats one host across twenty ports is one lookup on our side, so it is one address on your budget, and there is no need to deduplicate before sending. Lines we reject as invalid or private are free for the same reason, since they never reach the lookup at all. Your budget per IP is 120,000 addresses in a burst, refilling 1,000 per second, and 2,000,000 per day.


        **Large batches stream.** The response starts arriving as soon as the first addresses resolve rather than after the last one, which is what makes a call this size practical. It is still a single JSON document with a single `results` array in your original order, so `res.json()` and `r.json()` keep working exactly as before; the bytes simply arrive in pieces. Budget a couple of minutes for a fully cold 100 000-address batch. Anything we have looked up in the last six hours comes back from cache, so a list you re-check is far faster than the first run.


        Addresses that cannot be resolved come back as `{ "ip": "…", "found": false }` rather than being dropped, so the arrays always line up.'
      tags:
      - IP location and ASN API
      parameters: []
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
              example:
                results:
                - ip: 45.79.12.44
                  country: US
                  city: Dallas
                  asn: 63949
                  asn_org: Akamai Technologies, Inc.
                  is_datacenter: false
                - ip: 24.48.0.1
                  country: CA
                  region: Quebec
                  city: Montreal
                  asn: 5769
                  asn_org: Videotron Ltee
                  is_datacenter: false
                - ip: 8.8.8.8
                  country: US
                  asn: 15169
                  asn_org: Google LLC
                  is_datacenter: true
        '400':
          description: Invalid input. The body names the field and the accepted set.
        '401':
          description: Missing or invalid API key.
        '429':
          description: Rate limited. Retry after the delay in the response.
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                ips:
                  type: array
                  items: {}
                  description: Up to 100 000 IP addresses. A bare JSON array is also accepted. More than 100 000 returns 400 batch_too_large.
              required:
              - ips
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: Your API key. Free keyless endpoints ignore it.
x-endpoint-count: 163
x-generated-from: https://hproxy.com/docs
x-llms: https://hproxy.com/llms-full.txt