API changes

[gboeing]

Over the past year leading up to the release of OSMnx v1.0, there have been some API changes, new functions/modules added, and old functions deprecated. This meta-issue consolidates and documents these changes in case there are user questions.

See the docs and the usage examples for more details. For a summary of changes in v1.1, released May 2021, see #655.

Streamlined API

Over time, the OSMnx API and top-level namespace had become cluttered and increasingly unintuitive. Many of its modules had similarly grown unwieldy and its functional organization needed a rethink. The newly redesigned API:

• imports the primary user functions from the various modules directly into the ox. namespace (comprising the vast majority of end-user use cases)
• allows all other less-common user functions to be accessed via ox.module_name.function_name()
• makes all internal functions private/hidden

Everything in the users' reference is a public function. Every function can be accessed via ox.module_name.function_name() and the vast majority of them can also be accessed directly via ox.function_name() as a shortcut. Only a few less-common functions are accessible only via ox.module_name.function_name().

As of v0.13.0, all internal functions have been made "underscore" private per standard Python convention. This should have happened years ago and been the case all along, but it fell by the wayside along the way. Finally it's been done properly. Internal functions are not designed for public consumption and could change between minor releases as they are not meant to be part of the public API. However, they can still be accessed via ox.module_name._function_name(). Note the underscore preceding the function name, per standard Python convention. The private internal functions are documented alongside everything else in the internals reference guide.

For example:

ox.plot.get_colors(5)
ox.utils_geo._quadrat_cut_geometry(geom, 20000)
ox.utils_graph.get_largest_component(G)

See also this post.

Function and module changes

footprints and pois modules

The footprints and pois modules were deprecated in a previous release and have been removed and replaced by the geometries module, which is a more flexible and powerful replacement enabling users to download any geospatial objects from OSM and create a GeoDataFrame from them. The geometries module uses the same tag:value querying logic as the deprecated pois module did. These deprecated modules' functions, such as pois_from_place() or footprints_from_place(), are replaced by the geometries module's geometries_from_place() (and equivalent) functions.

For example, to download all the building footprints in some place as a GeoDataFrame:

gdf = ox.geometries_from_place(place, tags={'building':True})

Or, to get all local amenities, objects tagged landuse = retail or commercial, and objects tagged highway = bus_stop:

tags = {'amenity':True, 'landuse':['retail','commercial'], 'highway':'bus_stop'}
gdf = ox.geometries_from_place(place, tags)

gdf_from_place and gdf_from_places

The gdf_from_place and gdf_from_places functions were deprecated in a previous release and eventually removed. They have been replaced by the geocoder module's geocode_to_gdf function (see the docs), which is a drop-in replacement:

city = ox.geocode_to_gdf('Manhattan, New York, USA')

You can also now query by OSM ID using this function.

plot_shape

The plot_shape function was deprecated in a previous release and eventually removed. You can recreate its functionality directly with geopandas plotting, like this:

city = ox.geocode_to_gdf('Manhattan, New York, USA')
ax = ox.project_gdf(city).plot(fc='gray', ec='none')
_ = ax.axis('off')

save_gdf_shapefile

The save_gdf_shapefile function was deprecated in a previous release and eventually removed. You can recreate its functionality directly with geopandas saving, like this:

place_names = ['Berkeley, California, USA', 'Emeryville, California, USA']
east_bay = ox.geocode_to_gdf(place_names)
east_bay.to_file('./data/east_bay')

Node/edge structure

The old streets_per_node graph attribute was replaced by an equivalent street_count node-level attribute. The old osmid node attribute was removed because it was redundant with the node ID itself. The graph_to_gdfs function now multi-indexes the edges GeoDataFrame by u, v, key to mimic the structure of a NetworkX MultiDiGraph, and, reciprocally, the graph_from_gdfs function expects an edges GeoDataFrame multi-indexed by u, v, key.

Miscellaneous

OSMnx now caches server responses by default. This can be changed with ox.config(use_cache=False). The caching hash algorithm was changed for v1.0, invalidating old caches made with prior releases.

The graph_from_file function was deprecated in a previous release and eventually renamed graph_from_xml. The io.save_graph_xml was moved (with a user warning) to the new osm_xml module that contains all private/internal .osm XML functionality.

The clean_intersections function was deprecated in a previous release and replaced with a more powerful consolidate_intersections function that allows either geometric or topological processing.

The gdfs_to_graph function was deprecated in a previous release and eventually renamed graph_from_gdfs.

The infrastructure parameter was deprecated and eventually replaced by a streamlined, flexible custom_filter parameter for all the ox.graph_from_whatever functions. The distance parameters were similarly replaced with a uniform dist parameter.

See the docs and the usage examples for more details.

[ZAHRAZ-GH]

Hello, i want to download boundary from "place = ox.gdf_from_place('Piedmont, California, USA')", but i got this error:
" module 'osmnx' has no attribute 'gdf_from_place'"
as you pot this part # get the total area within Piedmont's admin boundary in sq meters), on your notebook of plantezian's course.

i replace ox.gdf_from_place to ox.geometries.geometries_from_place, but i could not access to Piedmont's admin boundary in sq meters. because i want to calculate the "what proportion of piedmont is covered by building footprints?"
can you help me? how can i download the area of boundaries . i could not found the "tage" for this goal.

[gboeing]

@ZAHRAZ-GH Thanks for using OSMnx! Please re-read the contributing guidelines and please remember that we do not use the issue tracker for "how-to" or usage questions. If asked here, they will be closed automatically. Instead, ask "how-to" and usage questions on StackOverflow. Please note that your question is already answered by the documentation and usage examples.