]> Google LLC

warren@kumari.net

Operations and Management Operations and Management Area Working Group geofeed geolocation ip geolocation json This document defines a JavaScript Object Notation (JSON) format for self-published IP geolocation feeds. It updates RFC 8805 by transitioning from the current comma-separated values (CSV) format to a more expressive JSON format, addressing the need for operational extensibility. About This Document The latest revision of this draft can be found at . Status information for this document may be found at . Discussion of this document takes place on the Operations and Management Area Working Group Working Group mailing list (), which is archived at . Subscribe at . Source for this draft and an issue tracker can be found at .

Introduction Section 2.1 defines a CSV-based format for network operators to publish a mapping of IP address prefixes to simplified geolocation information. While widely deployed, the authors of acknowledged in Section 7that the CSV format has "extremely limited extensibility" and that future work should involve the development of a more expressive format, specifically suggesting JSON (see, Section 7. "Planned Future Work"). Furthermore, identified several critical gaps in the existing geofeed ecosystem, including:

• The CSV format cannot adequately express varying levels of confidence in a location mapping (, Section 4.2), nor can it map a prefix to multiple locations (, Section 5.2) for example if the prefix is used for Anycast.
• The current format lacks the ontology to clarify whether the geolocation mapping refers to the physical location of the user, the location of network infrastructure, a network egress point, or a regulatory jurisdiction (, Section 3.3).

Note that also identified other, more architectural issues, including that physical location does not necessarily correspond to network topologies, the lack of user consent mechanisms, the potential for privacy violations, the need for different levels of precision (e.g. "get me to a close datacenter" vs "the ambulance needs my physical address", etc). However, these issues, while very important, are orthogonal to the data format and should be addressed through other mechanisms. This document simply tries to improve the data format to better support the ecosystem as it currently exists, while providing a framework for future extensions. Readers are strongly encouraged to read , the accompanying papers from the IAB Workshop on IP Address Geolocation for a deeper understanding of these architectural issues and the broader context of geolocation in the modern internet. and are particularly recommended to understand the architecture, use-case and privacy considerations in the original design. This document defines defines a new JSON-based format to address the extensibility limitations of the current CSV format, while maintaining compatibility with the core fields defined in . It also introduces new fields to address some of the gaps identified in .

Conventions and Definitions The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 when, and only when, they appear in all capitals, as shown here.

JSON Geofeed Format

Metadata section A compliant geofeed MUST include a new section comprised of a JSON object including certain fields which improve the operational usefulness of the information within. REQUIRED fields in this section include:

• last_updated: The time and date the feed was last generated, formatted as an ISO 8601 date-time.
• contact: An email addresss or URL (e.g., for a web form) for outreach about the geofeed for operational or other issues.
• update_frequency: The time, expressed either in a number of seconds or as an ISO 8601 duration. E.g., 86400 (seconds) or P1D (ISO 8601) each represent a daily interval.

OPTIONAL fields in this section include:

• source: The type of entity generating the geofeed information. Values include ISP, CDN, geo_provider, registry.
• applicability_statement: A text field describing how the data is intended to be used.

Body section The JSON format for geolocation feeds builds upon the fields specified in RFC 8805: IP prefix, alpha2code, region, city. Note that, as deprecated the use of the postal code field (, Section 2.1.1.5 - "Postal Code"), the JSON format does not support it. A JSON geofeed MUST be an array of JSON objects. Each object MUST contain the following keys:

• ip_prefix: same semantics as defined in
• alpha2code: same semantics as defined in
• region: same semantics as defined in
• city: same semantics as defined in

In addition, each object MUST contain:

• last_updated: A string indicating the timestamp of the last update to that record, formatted as an ISO 8601 date-time. This field is critical for consumers to assess the freshness of the data, given the dynamic nature of IP address allocations and network changes.

Objects MAY contain the following optional keys:

• location_type (optional): A string indicating the nature of the location.
• Valid values include infrastructure, network_egress, organization and jurisdiction.
• confidence (optional): A string expressing the certainty level of the mapping (, Section 5.2). Valid values include high, medium, and low.

Example JSON Geofeed Entry: The location_type field allows publishers to clarify the context of the geolocation mapping, while the confidence field provides a mechanism to express the reliability of the data. The last_updated field helps consumers assess the freshness of the information, which is crucial given the dynamic nature of IP address allocations and network changes. {Editor note: Multiple people have suggested new fields that should be added to the format, but we need to be careful about scope creep. These are only some of the proposed fields, but any others such as source, accuracy_radius and access_technology have also been discussed. For example, access_technology would be used to indicate the type of network access, such as wifi, cellular, or ethernet, and / or speed, jitter, etc. I have intentionally kept the initial list the same as RFC8805, but added last_updated as it was obviously needed, and location_type and confidence as examples. There will need to be careful discussion of other potential fields before they are added to the format, and it is possible that there will need to be a dedicated venue for such discussions. In addition, we might consider creating a registry for these fields to ensure consistency and interoperability, and a mechanism to provide "private" extensions.}

Security Considerations As noted in RFC 8805, self-publication of location data opens no new attack vectors, but consumers must validate inputs from potentially hostile sources. The JSON format allows for greater specificity, which increases the necessity for publishers to verify they have operational authority over the advertised prefixes and to ensure the accuracy of the geolocation data. Consumers should also be aware of the potential for stale data and consider the last_updated field when making decisions based on geofeed information.

IANA Considerations This document has no IANA actions.

References Normative References This document records a format whereby a network operator can publish a mapping of IP address prefixes to simplified geolocation information, colloquially termed a "geolocation feed". Interested parties can poll and parse these feeds to update or merge with other geolocation data sources and procedures. This format intentionally only allows specifying coarse-level location. Some technical organizations operating networks that move from one conference location to the next have already experimentally published small geolocation feeds. This document describes a currently deployed format. At least one consumer (Google) has incorporated these feeds into a geolocation data pipeline, and a significant number of ISPs are using it to inform them where their prefixes should be geolocated. In many standards track documents several words are used to signify the requirements in the specification. These words are often capitalized. This document defines these words as they should be interpreted in IETF documents. This document specifies an Internet Best Current Practices for the Internet Community, and requests discussion and suggestions for improvements. RFC 2119 specifies common key words that may be used in protocol specifications. This document aims to reduce the ambiguity by clarifying that only UPPERCASE usage of the key words have the defined special meanings. Informative References

Acknowledgments The authors would like to thank the participants of the IAB Workshop on IP Address Geolocation for their valuable insights and feedback, which have greatly informed the development of this document. In particular, the authors would like to thank the following individuals for their contributions to the discussions that led to the development of this document: Nimrod Levy, Jari Arkko, Brian Trammell, Erik Kline, Erik Nygren, Geoff Huston, Jari Arkko, Jason Livingood, Joe Abley, Joe Clarke, Joel Jaeggli, Jana Iyengar, Lee Howard, Robert Kisteleki, Tommy Pauly and Zoltan Szamonek. The authors would especially like to thank Tony Tauber for submitting useful pull requests.

Appendix A: Example Conversion Script The following Python program (convert.py) demonstrates how to convert an RFC 8805 format CSV geofeed into the JSON format defined in this document. This script reads from standard input and outputs the JSON to standard output. Note that this is a simple example script and does not include error handling, validation, or support for all potential fields. It is intended for illustrative purposes only. --- CODE BEGINS --- --- CODE ENDS --- The following Python program (test_convert.py) includes unit tests for the conversion script, demonstrating how to test the conversion of CSV input into the expected JSON output. --- CODE BEGINS --- --- CODE ENDS ---