Corrections API

What the corrections form sends, from a script: a POST request to https://ipapi.is/app/api-corrections with your API key.

The JSON body has the key, the type of the correction and its data. The networks in the examples are reserved for documentation, so the API refuses them as they stand: put in yours.

A location

Send the networks as geofeed lines, prefix,country,region,city,postal, of which a line needs the first two. They are applied as submitted with the next database build, whatever our other sources say.

curl https://ipapi.is/app/api-corrections \
  --header "Content-Type: application/json" \
  --data '{
    "key": "YOUR_API_KEY",
    "type": "geofeed",
    "data": {
      "geofeedData": [
        "203.0.113.0/24,DE,DE-BE,Berlin,10115",
        "2001:db8:42::/48,FR,,Paris,"
      ],
      "verificationSource": "We operate these networks."
    }
  }'

Or name a geofeed that you publish, in place of the lines. We fetch it with every build from then on:

"data": { "geofeedUrl": "https://example.net/geofeed.csv" }

Other data

Name the field of the API response as dataPoint, and pair each IP address, network or AS number with the value it should have. A person reads these, and details tells them how you know.

curl https://ipapi.is/app/api-corrections \
  --header "Content-Type: application/json" \
  --data '{
    "key": "YOUR_API_KEY",
    "type": "general",
    "data": {
      "general": {
        "dataPoint": "is_vpn",
        "corrections": [
          ["203.0.113.7", false],
          ["198.51.100.0/24", false]
        ],
        "details": "These are the addresses of our office."
      }
    }
  }'

A dataPoint is a field such as is_datacenter, company.name or asn.type, or company.* for several fields of one object. An unknown one is answered with the list of all. A location is corrected with geofeed lines: sent as a location field here, it changes nothing by itself.

The answer

{
  "message": "Correction received. It is applied as submitted with the next database build.",
  "authenticated": true
}

Anything else has an error that says what to change:

Status Reason
400 The correction cannot be used. The error names the line, the address or the field.
401 The API key is missing or unknown.
403 The account is suspended.
429 More than 200 corrections within an hour. Retry-After has the seconds to wait.

Limits

  • A request holds up to 1,000 lines or pairs, and either lines or a URL.
  • A prefix is a network or a single address in public address space, no larger than a /9 for IPv4 and a /17 for IPv6.
  • The country is a two-letter ISO 3166-1 code.
  • A geofeedUrl is fetched when you send it, and has to answer with HTTP 200 and a plain-text geofeed.