Augmented Diffs

This module provides classes for working with OSM Augmented Diffs. For more information about OSM Augmented Diffs, see the Augmented Diff page on the OpenStreetMap Wiki.

AugmentedDiff

Basic usage of the AugmentedDiff class:

>>> from osmdiff import AugmentedDiff
>>> ad = AugmentedDiff()
>>> ad.get_state()
True
>>> ad.sequence_number
6509700
>>> ad.retrieve()
200
>>> ad.sequence_number
6509701
>>> ad
AugmentedDiff (2776 created, 927 modified, 6999 deleted)
>>> ad.retrieve()
200
>>> ad.sequence_number
6509702
>>> ad
AugmentedDiff (3191 created, 1724 modified, 7077 deleted)  # the results of the two calls to retrieve() are merged

osmdiff.augmenteddiff.AugmentedDiff

Bases: object

An Augmented Diff representation for OpenStreetMap changes.

This class handles the retrieval and parsing of OpenStreetMap augmented diffs, which contain detailed information about changes made to OSM data, including creations, modifications, and deletions.

Parameters:

Name	Type	Description	Default
minlon	float | None	Minimum longitude of bounding box	None
minlat	float | None	Minimum latitude of bounding box	None
maxlon	float | None	Maximum longitude of bounding box	None
maxlat	float | None	Maximum latitude of bounding box	None
file	str | None	Path to an augmented diff file to parse	None
sequence_number	int | None	Sequence number of the augmented diff	None
timestamp	datetime | None	Timestamp of the augmented diff	None

Attributes:

Name	Type	Description
base_url		Base URL for the Overpass API
create		List of created OSM objects
modify		List of modified OSM objects (containing old and new versions)
delete		List of deleted OSM objects
remarks		List of remarks from the augmented diff
timestamp		Timestamp of the augmented diff

Raises:

Type	Description
Exception	If an invalid bounding box is provided
ValueError	If sequence_number is not parseable as an integer

Example

# Create an AugmentedDiff instance with a bounding box
adiff = AugmentedDiff(
    minlon=-0.489,
    minlat=51.28,
    maxlon=0.236,
    maxlat=51.686
)

# Get the current state
adiff.get_state()

# Retrieve the diff
status = adiff.retrieve()
if status == 200:
    print(f"Created: {len(adiff.create)}")
    print(f"Modified: {len(adiff.modify)}")
    print(f"Deleted: {len(adiff.delete)}")

__exit__(exc_type, exc_val, exc_tb)

Clear all changes when exiting context.

get_state(base_url=None, timeout=None) classmethod

Get the current sequence number from the OSM API.

Parameters:

Name	Type	Description	Default
base_url	Optional[str]	Optional override for API base URL	None
timeout	Optional[int]	Optional override for request timeout	None

Returns:

Type	Description
Optional[int]	Current sequence number if successful, None if failed

retrieve(clear_cache=False, timeout=None, auto_increment=True, max_retries=3)

Retrieve the Augmented diff corresponding to the sequence_number.

Parameters:

Name	Type	Description	Default
clear_cache	bool	Whether to clear existing data before retrieval.	False
timeout	Optional[int]	Request timeout in seconds.	None
auto_increment	bool	Whether to automatically increment sequence number after retrieval.	True
max_retries	int	Maximum number of retry attempts for failed requests.	3

Returns:

Type	Description
int	HTTP status code of the request (200 for success)

Raises:

Type	Description
Exception	If sequence_number is not set
RequestException	If all retry attempts fail

ContinuousAugmentedDiff

The ContinuousAugmentedDiff class provides an iterator interface for continuously fetching augmented diffs as they become available. It handles timing, backoff, and error recovery automatically.

Basic usage:

>>> from osmdiff import ContinuousAugmentedDiff
>>> # Create fetcher for London area
>>> fetcher = ContinuousAugmentedDiff(
...     minlon=-0.489,
...     minlat=51.28,
...     maxlon=0.236,
...     maxlat=51.686
... )
>>> # Iterate over diffs as they become available
>>> for diff in fetcher:
...     print(f"Got diff {diff.sequence_number} with {len(diff.create)} creates")
Got diff 6509701 with 2776 creates
Got diff 6509702 with 3191 creates
# ... continues until interrupted

osmdiff.augmenteddiff.ContinuousAugmentedDiff

Iterator class for continuously fetching augmented diffs.

This class handles the continuous retrieval of augmented diffs with proper backoff and state checking. It yields AugmentedDiff objects as new diffs become available.

Parameters:

Name	Type	Description	Default
minlon	float | None	Minimum longitude of bounding box	None
minlat	float | None	Minimum latitude of bounding box	None
maxlon	float | None	Maximum longitude of bounding box	None
maxlat	float | None	Maximum latitude of bounding box	None
base_url	str | None	Override default Overpass API URL	None
timeout	int | None	Request timeout in seconds	None
min_interval	int	Minimum seconds between checks (default: 30)	30
max_interval	int	Maximum seconds between checks (default: 120)	120

Example

# Create continuous fetcher for London area
fetcher = ContinuousAugmentedDiff(
    minlon=-0.489,
    minlat=51.28,
    maxlon=0.236,
    maxlat=51.686
)

# Iterate over diffs as they become available
for diff in fetcher:
    print(f"Got diff {diff.sequence_number} with {len(diff.create)} creates")

__next__()

Get next available augmented diff.

Yields:

Name	Type	Description
AugmentedDiff	AugmentedDiff	Next available diff

Raises:

Type	Description
StopIteration	Never raised, iterates indefinitely