Overview

purposeThe root (or discovery) resource is the single entry point of an open511 endpoint. By following links from the discovery resource, clients can find and gain access to all resources within an Open511 implementation.
methodGET

Parameters and filters

The discovery resource does not support any URL parameter or filter besides the format selection and the language negotiation.

Example

Example of the XML and JSON representations of the discovery resource

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
<open511
    xml:lang="en"
    xml:base="http://api.open511.info/"
    version="v1"
>  
  <jurisdictions>
    <jurisdiction>
      <id>mycity.gov</id>
      <name>My City</name>
      <link rel="self" href="http://mycity.gov/open511/jurisdiction/mycity.gov/" />
    </jurisdiction>
    <jurisdiction>
      <id>mycounty.gov</id>
      <name>My County</name>
      <link rel="self" href="http://mycounty.gov/open511/jurisdiction/mycounty.gov/" />
    </jurisdiction>    
  </jurisdictions>
  <services>
    <service>
      <link rel="self" href="/events/" />
      <link rel="service_type" href="http://open511.org/services/events" />
    </service>
    <service>
      <link rel="self" href="/areas/" />
      <link rel="service_type" href="http://open511.org/services/areas" />
    </service>    
  </services>
</open511>
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
{
  "jurisdictions" : [
      {
          "id" : "mycity.gov", 
          "name" : "My City",           
          "url" : "http://mycity.gov/open511/jurisdiction/mycity.gov/"
      },
      {
          "id" : "myregion.gov", 
          "name" : "My Region",               
          "url" : "http://myregion.gov/open511/jurisdiction/myregion.gov/"
      }
  ],
  "services" : [
      {
          "service_type_url" : "http://open511.org/services/events",
          "url" : "/events/"
      },
      {
          "service_type_url" : "http://open511.org/services/events",
          "url" : "/areas/"
      }      
  ],
  "meta": {
      "version": "v1"
  }

}

Data structure

The following table provides the data structure for the root (discovery) resource.

Note that the discovery resource follows the rules of an individual item in formatting guidelines and not of list since it contains different types of items. There is no up link since the discovery is the upper level.

FieldTypeDescription
jurisdictionsCollection of jurisdiction

Mandatory, at least one jurisdiction element is mandatory

List all the jurisdictions that are supported by the endpoint. Most of the time, there will be only one occurrence, except for multiple jurisdictions endpoints and aggregators.

— id

String

Mandatory

ID of the jurisdiction.

— name

Free text

Mandatory

Full text name of the jurisdiction.

— self/url

Link

Mandatory

Link to the jurisdiction resource. In XML, the rel attribute needs the value self. An aggregator should always point the original jurisdiction resource and not copy it locally.

services

Collection of service

Mandatory

List all the services supported by the endpoint.

— service_type

Link

Mandatory

A URL representing an Open511 service like Events or Areas. The URL follows the same logic as an XML namespace: it's a unique identifier for the service type, though clients will never need to visit that URL. It's recommended that the URL point to human-readable documentation for the service.

All services that are part of this specification will have URLs starting with http://open511.org/services/. For virtually all implementors, this URL should be on open511.org. Other organizations may want to build services that are outside the current scope of this specification but otherwise fit in with the other Open511 services; such services will have URLs not on open511.org. Such services must follow the guidelines of this specification.

Values for current Open511 services are:

  • http://open511.org/services/events/
  • http://open511.org/services/events-static/
  • http://open511.org/services/areas/
  • http://open511.org/services/cameras/
  • http://open511.org/services/roads/
  • http://open511.org/services/traffic_segments/

— self/url

Link

Mandatory

Link pointing to the resource. In XML, the rel attribute needs the value self. Even if the current endpoint supports multiple jurisdictions or is an aggregator, there is only one service resource that aggregates the data for all the jurisdictions.

—supported_versions

Collection of supported_version

Optional

List all the versions supported by the current server.

— — supported_version

Enum

Optional

Version identifier. As the specification evolves, version identifiers will be added. For the moment, the only version supported is v0 and is not an official value.