--- title: "Example values for docs: IPs, domains, phone numbers" description: "Reserved values for documentation and tests: example domains, IP ranges (RFC 5737, RFC 3849), AS numbers, MAC addresses, phone numbers and test cards." url: https://example-petstore.com/guides/example-values language: en --- # Example values that are safe to use Documentation, tutorials and tests need addresses, numbers and names that look real but never reach anyone. For most kinds of value a reserved range exists. This guide lists them, with the source for each, so examples stay harmless when someone copies them. ## Why reserved values Examples get copied: into code, configuration files, tests and other documentation. A value that looks invented but belongs to someone sends that traffic, those e-mails or those calls to a real party. example-petstore.com is a case in point: an invented name in Google’s documentation that anyone could register, and that still receives requests. Reserved values are guaranteed never to be assigned, so a copied example fails harmlessly. ## Domain names and e-mail For websites, APIs and e-mail addresses in examples, use `example.com`, `example.net` or `example.org` and their subdomains, such as `api.example.com` and `user@example.com`. For test environments, names that must never resolve and local networks there are `.test`, `.invalid`, `.localhost`, `home.arpa` and `.internal`. What each reserved name is for, and why look-alikes such as example-petstore.com are not safe: [Example domains](https://example-petstore.com/example-domains) ## IP addresses | Type | Reserved for documentation | Source | | --- | --- | --- | | IPv4 | `192.0.2.0/24` (TEST-NET-1), `198.51.100.0/24` (TEST-NET-2), `203.0.113.0/24` (TEST-NET-3) | RFC 5737 | | IPv6 | `2001:db8::/32` | RFC 3849 | | IPv6, larger networks | `3fff::/20` | RFC 9637 (2024) | ``` # A client, a server and a proxy in an example client 192.0.2.10 2001:db8::10 server 198.51.100.20 2001:db8:1::20 proxy 203.0.113.30 2001:db8:2::30 ``` The three IPv4 blocks give an example three separate “networks”, which helps when explaining routing or firewalls. `3fff::/20` exists because `2001:db8::/32` is too small to show realistic allocations for large providers. ## AS numbers For BGP examples: `64496`–`64511` (16-bit) and `65536`–`65551` (32-bit), reserved for documentation by RFC 5398. Private-use AS numbers are meant for real networks, not for examples. ## MAC addresses `00-00-5E-00-53-00` to `00-00-5E-00-53-FF` (written as `00:00:5e:00:53:00` in most tools) are reserved for documentation by RFC 9542 (which replaced RFC 7042). ## Phone numbers There is no worldwide range; several countries reserve their own for fiction and examples: - **United States and Canada:** `555-0100` to `555-0199`, with any area code, such as `+1 202 555 0143`. - **United Kingdom** (Ofcom): mobile `07700 900000` to `07700 900999`, London `020 7946 0000` to `020 7946 0999`, and `01632 960000` to `01632 960999` without a specific area. For other countries, check the telecom regulator. Where no range exists, use a placeholder that cannot be dialled, such as `+31 6 XXXX XXXX`, rather than digits that merely look random. ## Payment cards Payment providers publish test card numbers that only work in their test mode, such as Stripe’s `4242 4242 4242 4242` with any future expiry date and any CVC. Use the numbers of the provider you are integrating with; test numbers from one provider are not accepted by another. Never use a real card number, not even your own, in documentation, fixtures or screenshots. ## What not to use - **Invented look-alike domains** such as example-petstore.com, mycompany.com or test.com: they can be, and often are, registered. - **Private address ranges** such as `10.0.0.0/8` or `192.168.0.0/16` in public documentation: they exist in the reader’s own network, so a copied example may reach a real device there. - **Real-looking API keys**: write a clear placeholder such as `YOUR_API_KEY` or `sk_test_…`, never a key that was ever valid. - **Real people’s data**: names, e-mail addresses and phone numbers of colleagues or customers do not belong in examples or test fixtures. ## Related guides ### [Configuring API clients and SDKs](https://example-petstore.com/guides/api-base-url) Keep base URLs out of code, point them at the real service, and add a check that stops example addresses from reaching production. ### [Test against a mock API, not a placeholder](https://example-petstore.com/guides/mock-api) Develop and test against Prism, WireMock, MSW or json-server instead of an address that belongs to someone else. ### [Looking for the Swagger Petstore?](https://example-petstore.com/guides/swagger-petstore) The real base URLs of the Swagger Petstore sample API, working requests, the test key, and how to run your own copy with Docker. ## Sources - [RFC 2606: Reserved Top Level DNS Names](https://www.rfc-editor.org/rfc/rfc2606.html) IETF - [RFC 6761: Special-Use Domain Names](https://www.rfc-editor.org/rfc/rfc6761.html) IETF - [RFC 8375: Special-Use Domain home.arpa](https://www.rfc-editor.org/rfc/rfc8375.html) IETF - [Reserving .INTERNAL for private-use applications](https://www.icann.org/en/board-activities-and-meetings/materials/approved-resolutions-special-meeting-of-the-icann-board-29-07-2024-en) ICANN - [RFC 5737: IPv4 Address Blocks Reserved for Documentation](https://www.rfc-editor.org/rfc/rfc5737.html) IETF - [RFC 3849: IPv6 Address Prefix Reserved for Documentation](https://www.rfc-editor.org/rfc/rfc3849.html) IETF - [RFC 9637: Expanding the IPv6 Documentation Space](https://www.rfc-editor.org/rfc/rfc9637.html) IETF - [RFC 5398: AS Number Reservation for Documentation Use](https://www.rfc-editor.org/rfc/rfc5398.html) IETF - [RFC 9542: IANA Considerations and IETF Protocol and Documentation Usage for IEEE 802 Parameters](https://www.rfc-editor.org/rfc/rfc9542.html) IETF - [555 Line Numbers](https://www.nanpa.com/numbering/555-line-numbers) NANPA - [Telephone numbers for drama](https://www.ofcom.org.uk/phones-and-broadband/phone-numbers/numbers-for-drama) Ofcom - [Test card numbers](https://docs.stripe.com/testing) Stripe