{"id":15284685,"url":"https://github.com/rjpolackwich/chauffeur","last_synced_at":"2025-04-12T23:43:58.277Z","repository":{"id":62561802,"uuid":"414029600","full_name":"rjpolackwich/chauffeur","owner":"rjpolackwich","description":"Python api for building and querying OSM via OverpassQL","archived":false,"fork":false,"pushed_at":"2022-05-26T00:16:11.000Z","size":27,"stargazers_count":3,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-04-12T23:43:55.497Z","etag":null,"topics":["openstreetmap","openstreetmap-data","osm","overpass-api","overpass-ql"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/rjpolackwich.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2021-10-06T01:18:50.000Z","updated_at":"2025-03-05T05:12:45.000Z","dependencies_parsed_at":"2022-11-03T15:01:00.149Z","dependency_job_id":null,"html_url":"https://github.com/rjpolackwich/chauffeur","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rjpolackwich%2Fchauffeur","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rjpolackwich%2Fchauffeur/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rjpolackwich%2Fchauffeur/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rjpolackwich%2Fchauffeur/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/rjpolackwich","download_url":"https://codeload.github.com/rjpolackwich/chauffeur/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248647256,"owners_count":21139081,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["openstreetmap","openstreetmap-data","osm","overpass-api","overpass-ql"],"created_at":"2024-09-30T14:59:25.439Z","updated_at":"2025-04-12T23:43:58.257Z","avatar_url":"https://github.com/rjpolackwich.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Chauffeur\n[Chauffeur](https://github.com/rjpolackwich/chauffeur) was designed to provide an intiutive and easy to get started with building and making [Overpass](https://python-overpy.readthedocs.io/en/latest/) queries in Python. It is also built to empower users who are interested in using the OverpassQureryLanguage primitives to do things like data QA, data \"gardening,\" and otherwise through the consruction of more complex and logical queries. \n\nIn building Chauffeur, attention was taken to creating interfaces and naming conventions that shed light on some of the less understood aspects of Overpass, as well as [Open Street Map](https://wiki.openstreetmap.org/wiki/Main_Page)(OSM). The more we know about the kind of data out there on OSM, the better judements we can make when, eg, building QA metrics on results, as well as optimizing query requests, etc. Chauffeur is supposed to empower researchers to develop these kind of data intuitions and statistics by abstracting the Query Language itself, providing best practices as taken from Overpass, providing access to formatting and service params, and defining preconfigured objects for different use cases.\n\n## Installation\n```\npip install chauffeur-pass\n```\n\n## Getting Started\n\n```\nimport chauffeur as cfr\n```\nThe main entrypoint is the `chauffeur.QueryBuilder` object. It provides the interfaces for query construction, parameterization, and execution. Initialize a `QueryBuilder` to get started.\n```\nqb = cfr.QueryBuilder()\n```\n### Request and Query Parameters\nThe `settings` interface let's a user define Overpass-specific request+response parameters. Examples include global bounding boxes, global date filters, server timeouts, and data limits, as well as response format. Chauffeur defaults to the Overpass default request params, which means a blank string. If the Overpass default params aren't optimal for your query, you can change them:\n\n```\nqb.settings.timeout = 3600 # Set the Overpass server timeout in seconds\nqb.settings.maxsize = int(cfr.QuerySettings.MAXSIZE_LIMIT / 2) # Set the return payload to max 1GB\nqb.settings.payload_format = 'json' # Return results in JSON format instead of default XML\n```\nThese params can also be passed as keywords during `QueryBuilder` initialization.\n\nThe `output_mode` interface is meant to bridge the \"print\" concept in OverpassQL. The query output controls, or mode descriptors, are relevant to the way Overpass processes queries and returns information. The defaults are consistent with Overpass, but can be changed:\n```\nqb.output_mode.GEOMETRY = cfr.fmt.Geometry.CENTER_POINT\nqb.output_mode.VERBOSITY = cfe.fmt.Verbosity.VERBOSE\nprint(qb.output_mode)\n```\n\n### Defining Query Statements with Filters\nChaufeur provides various query filters accessible via the main `chauffeur` module. These are: `chauffeur.UserFilter`, `chauffeur.IdFilter`, `chauffeur.BboxFilter`, and `chauffeur.TagFilter`. The following demonstrates some of the ways the `TagFilter` can be used to search for OSM tags, which are defined as key-value pairs.\n\nThe following defines a filter for schools - namely, a tag with key \"amenity\" and value \"school\":\n```\nschools = cfr.TagFilter(\"amenity\", \"school\")\n```\nThis would filter elements that have an \"amenity\" key that includes the tag value \"school\". To extend the search to include other elements, you can include them as a list of values: \n```\nplaces_of_study = cfr.TagFilter(\"amenity\", [\"school\", \"university\", \"college\"])\n```\nInstead of creating three different filters on the same tag key, chauffeur concatenates the values into a regex string, which is supported by Overpass and is considered a best practice.\n\nWe can match a tag key with any value whatsoever by excluding input vals:\n```\nany_amenity = cfr.TagFilter(\"amenity\")\n```\nFiltering by non-existence is supported as well:\n```\nno_amenities = cfr.TagFilter(\"amenity\", exists=False) # Disallow any object with \"amenity\" key and any values\namenities_no_learning = cfr.TagFilter(\"amenity\", [\"school\", \"university\", \"college\"], exists=False) # Find amenities without educational tags\n```\nFeatures of interest are often characterized by multiple combinations of tag filter values. We can create compound tag filters through union:\n```\nrailstations = cfr.TagFilter(\"railway\", \"station\") + cfr.TagFilter(\"public_transport\", \"station\")\n```\n\n### Building and Setting Query Statements\nThe OSM type paradigm is used to classify the \"geometry\" of an element, so to speak, which can be one of Node, Way, or Relation. A query statement consist of a stated set of elements to search for, and one of more filters. Chauffeur provides a query element interface for defining query statements.\n\nThe following asks for school tags classified as node objects in OSM:\n```\nschools_as_node_types = cfr.NodeQuery(filters=schools)\n```\nBut not all schools are nodes; we might like to get ways and relations as well:\n```\nschools_as_all_types = cfr.NodeWayRelationQuery()\nschools_as_all_types.add_filter(schools)\n```\nWe can add more filters to the school query, or can combine the output of this query with something else we might be interested in, again using the plus sign for unioning:\n```\nbeerstores = cfr.TagFilter(\"shop\", \"alcohol\")\nbeerstores_as_all_types = cfr.NodeWayRelationQuery(filters=beerstores)\nschools_and_beerstores_query = schools_as_all_types + beerstores_as_all_types\n```\nFinally, we set the constructed query statement to the `QueryBuilder` object.\n```\nqb.qsx.append(schools_and_beerstores_query)\n```\n\n### Setting AOI's and Getting Output\nWe can set settings, output formats, etc as we see fit. But because we have not included any cfr.BoundingBox filters, we are searching the whole world. Setting the QueryBuilder.GLobalBoundingBox attribute defines a bounding box filter for each statement in the whole query, and is part of the settings component; it is considered good practice to specify AOIs in this way:\n```\nqb.GlobalBoundingBox = [50.6,7.0,50.8,7.3] # A bbox framing the German city of Bonn\n```\nThe underlying OverpassQL string can be accessed through a property:\n```\nqb.raw_query_string\n```\nFinally, we can perform a query of all Node, Way, and Relation elements that identify both schools and beer stores in Bonn, Germany, by submitting our request to the Overpass servers, and get our results back as JSON:\n```\nresults = qb.request()\n```\n\n\n\n\n\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frjpolackwich%2Fchauffeur","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frjpolackwich%2Fchauffeur","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frjpolackwich%2Fchauffeur/lists"}