Publishing a Geofeed

If you'd like to correct the geolocation information associated with the networks you own or administer for your clients the preferred way to do this is via geofeeds.

What is a Geofeed?

Geofeeds are the gold standard for sharing geolocation information and have been discussed and described in great detail in RFC 8805.

A geofeed is simply a CSV file with the following format:

network, iso_country code, iso_region_code, city_name, postal_code

Here is an example of a valid and complete geofeed;

8.8.8.0/24,US,US-CA,Mountain View,
2001:4860:4860::/46,US,US-CA,Mountain View,

That's it!

ColumnDescription
networka valid IP address or network, either is fine, both IPv4 and IPv6 are supported
iso_country_codea valid ISO 3166-1 alpha-2 code, you can find a list of all the ISO country codes at https://en.wikipedia.org/wiki/List_of_ISO_3166_country_codes#UNI4
iso_region_codea valid ISO 3166-2 code, you can find a list of all the ISO region codes for a specific country at https://en.wikipedia.org/wiki/List_of_ISO_3166_country_codes#UNI4. Simply look under the "Subdivision Code links" column for the country you're interested in. Alternatively, if you know the country code, append it to the following url https://en.wikipedia.org/wiki/ISO_3166-2:{ your iso country code} eg. https://en.wikipedia.org/wiki/ISO_3166-2:US
city_namethe city you'd like to associate with the network
postal_code (optional)the postal code you'd like to associate with the network

Note that all except the network and the country code are optional. Technically the RFC states that the country code is optional but we will not process any entries that do not have a country code at a minimum.

Publishing your Geofeed

You have a few options:

Google Spreadsheets

This is the simplest way to get started! Simply upload your csv file to Google Sheets and send us the public URL. If you have a few networks you can just use the spreadsheet as a living geofeed and update it whenever you need to so long as you follow the format described in the previous section.

Github Repo

Another very simple solution is to create a public Github repo and push your geofeed to it. Then share the repo with us! You can update the file as needed with the added advantage that you will have a history of all the changes.

Your website

This is the most formal way to share your geofeed and is the existing convention.

Upload your geofeed file to your company's domain eg. example.com/geofeed.csv or geofeed.example.com.

Validating your feed

We have added a validate command to the ipdata CLI that you can use to ensure all the entries in your geofeed will be processed without issue.

If you don't already have the CLI, use pip to install it

python3 -m pip install ipdata

Then run

ipdata validate https://example.com/geofeed.csv

to validate an already published feed.

Or to validate a local file run

ipdata validate myfeed.csv

The command checks that for every entry:

  • the country code is a valid ISO 3166-1 alpha-2 code
  • the region code is a valid ISO 3166-2 code
  • the region code and the country code match i.e. the region given is in the country given
  • the country code is not empty
  • the network is a valid network i.e. not a typo or a private/reserved network

Submitting to ipdata

Once you are happy with your feed and have uploaded it to a publicly accessible URL, please send an email with the link to [email protected]

Sharing your feed with a wider audience

If you'd like to share your geofeed with a wider audience you can do so by editing the inetnum information in whois and adding a geofeed: field with a link to your feed. This will allow your feed to be automatically discovered by any organizations that use geofeed data. This is described in greater detail in RFC 9092. eg.

inetnum: 192.0.2.0/24 # example
geofeed: https://example.com/geofeed.csv

Did this page help you?