Skip to content

Latest commit

 

History

History
273 lines (191 loc) · 10.9 KB

File metadata and controls

273 lines (191 loc) · 10.9 KB

Mobility Data Specification: Geography

MDS Geography Icon

This specification contains a collection of RESTful APIs used to read Geographies (descriptions of geographical information, e.g. multi-polygons, currently represented via GeoJSON).

Geographical data has many applications in the context of mobility, such as the description of municipal boundaries, locations for pick-up and drop-off zones, and areas of temporary closure for special events or emergencies. This API is intended to support a variety of other APIs, including the Policy API.

Geographical data will be stored as GeoJSON and read from either geographies.json or the /geographies endpoint, referenced by UUID. Geography data once published through this API shall be treated as immutable, to ensure that any rules or regulations referring to the boundaries cannot be retroactively changed. A Geography may be deprecated and replaced by updated version with a new UUID.

Table of Contents

General Information

The following information applies to all geography API endpoints.

Top

Authorization

This endpoint should be made public. Authorization is not required.

Top

Versioning

MDS APIs must handle requests for specific versions of the specification from clients.

Versioning must be implemented as specified in the Versioning section.

Top

Distribution

Geographies shall be published by regulatory agencies or their authorized delegates as JSON objects. These JSON objects shall be served by either flat files or via REST API endpoints. In either case, geography data shall follow the schema outlined below.

Published geographies, should be treated as immutable data. Obsoleting or otherwise changing a geography is accomplished by publishing a new geography with a field named prev_geographies, a list of UUID references to the geography or policies geographies by the new geography.

Geographical data shall be represented as GeoJSON FeatureCollection objects. Typically no part of the geographical data should be outside the municipality boundary unless an agency has the authority to regulate there.

Geographies should be re-fetched at an agreed upon interval between providers and agencies, or when either entity requests it.

Top

Flat Files

To use a flat file, geographies shall be represented in one (1) file equivalent to the /geographies endpoint:

  • geographies.json in Geography API

The files shall be structured like the output of the REST endpoints above.

The publishing Agency should establish and communicate to providers how frequently these files should be polled.

The last_updated field in the payload wrapper should be set to the time of publishing a revision, so that it is simple to identify a changed file.

Top

Response Format

See the Responses and Error Messages sections.

Top

Schema

See the Endpoints below for links to specific data objects, and the mds-openapi repository for full details and interactive documentation.

Top

Geography Fields

Name Type Required/Optional Description
name String Required Name of geography
description String Optional Detailed description of geography
geography_type String Optional Type of geography, e.g. municipal_boundary or council_district or custom text. See Geography Type.
geography_id UUID Required Unique ID of geography
geography_json JSON Required The GeoJSON that defines the geographical coordinates.
effective_date timestamp Optional The date at which a Geography is considered "live". Must be at or after published_date.
published_date timestamp Required Time that the geography was published, i.e. made immutable
retire_date timestamp Optional Time that the geography is slated to retire. Once the retire date is passed, new policies can no longer reference it and old policies referencing it should be updated. Retired geographies should continue to be returned in the geographies list. Must be after effective_date. Geographies referencing others with prev_geographies immediately replace the previous ones.
prev_geographies UUID[] Optional Unique IDs of prior geographies replaced by this one

Top

Previous Geographies

Obsoleting or otherwise changing a geography is accomplished by publishing a new geography with the prev_geographies field, which is a list of UUID references to the geography or geographies superseded by the new geography. The previous geographies are also published in the /geographies endpoint. Using it allows agencies to look back historically at previously published geographies, for analysis, historic reference, or an auditable change trail.

This field is optional can be omitted by the publishing Agency.

Top

Geography Type

Type of geography. These specific types are recommendations based on ones commonly defined by agencies. Others may be created by the Agency as needed, or the optional geography_type field may be omitted.

geography_type does not imply policy or required actions by providers, but instead is for organizational and discovery purposes within the standalone Geography API. Geographies need to be referenced from other areas of MDS to be meaningfully applied.

Value Description
municipal_boundary Edge of a city
policy_zone Zone where Policy rules could be in effect, like operating area, distribution/equity zones, no/slow ride zone, no parking, etc
county_boundary Edge of a county
stop See Stops
council_district City council district
political_district Politically defined voting area
neighborhood Neighborhood area
market_area Economic area
opportunity_zone Defined Opportunity Zone
overlay_district Agency overlay district
post_code Zip or postal code
traffic_zone Transportation planning area
property_line One or more property lines
right_of_way Public right of way area
census_block Census block
census_block_group Census block group
census_tract Census tract

Top

File format

Note: to use flat files rather than REST endpoints, Geography objects should be stored in geographies.json. The geographies.json file will look like the output of GET /geographies.

Example geographies.json

{
  "version": "2.0.0",
  "last_updated": "1682984274000",
  "geographies": [
    {
      // Geography 1
    },
    {
      // Geography 2
    }
  ]
}

Responses

Possible HTTP Status Codes: 200, 404, 406, 500

See Responses, Bulk Responses, and schema for details.

Top

Endpoints

Responses must set the Content-Type header, as specified in the Provider versioning section. They must also specify the API version in the JSON-formatted response body, under the version key.

The Geography API consists of the following endpoints:

Geography

Endpoint: /geographies/{geography_id}
Method: GET
Schema: See mds-openapi repository for schema.

Path Parameters

Path Parameter Type Required/Optional Description
geography_id UUID Required Unique identifier for a single specific Geography

Returns: Details of a single Geography based on a UUID.

Response body:

{
  "version": "2.0.0",
  "geography": {
    "geography_id": UUID,
    "geography_type": string,
    "name": string,
    "description": string,
    "published_date": timestamp,
    "effective_date": timestamp,
    "prev_geographies": UUID[],
    "geography_json": GeoJSON FeatureCollection
  }
}

Responses

Possible HTTP Status Codes: 200, 400 (with parameter), 404, 406, 500

See Responses, Bulk Responses, and schema for details.

Top

Geographies

Endpoint: /geographies
Method: GET
Schema: See mds-openapi repository for schema.

Returns: All geography objects

Response body:

{
  "version": "2.0.0",
  "last_updated": "1682984274000",
  "geographies": [
    {
      // Geography 1
    },
    {
      // Geography 2
    }
  ]
}

Responses

Possible HTTP Status Codes: 200, 404, 406, 500

See Responses, Bulk Responses, and schema for details.

Top

Examples

See the Geography Examples for ways these can be implemented and geometry previews.

Top