Collaboration for an Open311 Standard

Jump to: navigation, search

Note: some of this content is NYC-specific (such as URLs and Category values). Future updates to the specification will need to have these items separated out.

Use Inquiry v2 Draft to review and add ideas on the next iteration of this proposal.

Note: NYC's implementation is case-sensitive.

While it's not required, please consider registering for NYC's endpoint to be informed about any updates or changes to their API. Their registration page and more information can be found on nyc.gov

Get Services

Services are services and information that are offered to the public

The Get Services functionality consists of two methods. The first method, “Get Service List”, retrieves a list of all of the services when invoked. The second method, “Get Service”, retrieves detailed information about the Service requested when invoked.

Get Service List

This method retrieves a list of links to all services and a brief description of each Service. This method takes a category or a type as an optional input. If a category is provided, the list of Services returned will be restricted such that only Services which belong to that category will be included in the response.

URL

http://<content_api_root>/services/<category>.<content_type>

Sample URLs

Inputs

category (/type) – a category or type for a Service. If a category is supplied then the list of Services returned will be restricted to Services belonging to this category. The following categories are supported:

Category	URL Encoded Value
Transportation, Streets, and Sidewalks	Transportation%2C%20Streets%20and%20Sidewalks
Environment and Sanitation	Environment%20and%20Sanitation
Property, Buildings and Homes	Property%2C%20Buildings%20and%20Homes
Education and Employment	Education%20and%20Employment
Business and Finance	Business%20and%20Finance
Social Services	Social%20Services
Health and Medicine	Health%20and%20Medicine
Public Safety and Law	Public%20Safety%20and%20Law
Government and Civil Services	Government%20and%20Civil%20Services

The following types are supported:

Type	URL Encoded Value	Description
Top Mobile Services	mobile	Services selected by the 311 Content Team to be promoted as “Top Services” on the 311 iPhone application. (A service may exist as a top service for a web platform, a mobile platform or both).
Tob Web Services	web	Services selected by the 311 Content Team to be promoted as “Top Services” on the 311 Online Homepage. ( A service may exist as a top service for a web platform, a mobile platform or both).
Facility Finder Services	finder	311 Online services that have a Facility Finder functionality embedded on the service’s page.

Response Structure

Field Descriptions

id – the unique identifier of the Service record
service_name – name of the Service record
expiration – the date the Service expires. Expiration will occur at 12:00 AM of the date specified.
brief_description – a short description of the Service

Get Service

This method retrieves detailed information about the Service requested. Services are specified using the Id of the Service.

URL

http://<content_api_root>/services/<service_id>.<content_type>

Sample URLs

Inputs

service_id – the Id of the Service being requested.

Response Structure

Field Descriptions

id – the unique identifier of the Service record
service_name – the name of the Service record
expiration – the date the Service expires. Expiration will occur at 12:00 AM of the date specified.
categories – a list of taxonomy categories that the Service belongs to
url – the URL that points to the Service on 311 Online
brief_description – a short description of the Service
description – the detailed description of the Service, cleansed of HTML elements
description_html – the detailed description of the Service, contains HTML elements
web actions – a list of links or plain text that specify actions available pertaining to a service
type – the type of Web Action. Possible values are: “Service Request”, “Link”, and “Literature”
label – human readable text label for a web action
url – the URL for a Web Action that is a link

<services>
  <service>
    <id> 2003-07-21-11-45-37_000010083f1c0aa44000a0e7</id>
    <service_name> Home Ownership Kit</service_name>
    <expiration>2011-12-31T23:59:59Z</expiration>
    <cateogries>
      <category_name>Property, Buildings & Homes</category_name>
    </cateogries>
    <url> http://www.nyc.gov/apps/311/allServices.htm?requestType=topService&serviceName=Home+Ownership+Kit </url>
    <brief_description> Get a kit to guide you through the process of becoming a homeowner. </brief_description>
    <description> The City offers information about becoming a New York City homeowner, including: Lists of affordable homes that are currently accepting applications The steps of the buying process Down payment assistance Homebuyer education training</description>
    <description_html>
      <![CDATA[The City offers information about becoming a New York City homeowner, including:<br /><br /><ul class="dashes"><li>Lists of affordable homes that are currently accepting applications</li><li>The steps of the buying process</li><li>Down payment assistance</li><li>Homebuyer education training</li></ul>]]>
    </description_html>
    <web_actions>
      <web_action type="Link">
        <label> Get information about home ownership.</label>
        <url> http://www.nyc.gov/html/hpd/html/buyers/guide.shtml</url>
      </web_action>
      <web_action type="Link">
        <label> Download the Home Ownership Kit (PDF).</label>
        <url> http://www.nyc.gov/download/311/HPD/homeownership-kit.pdf</url>
      </web_action>
    </web_actions>
  </service>
</services>

[
  {
    "id":" 2003-07-21-11-45-37_000010083f1c0aa44000a0e7",
    "service_name":" Home Ownership Kit",
    "expiration":"2011-12-31T23:59:59Z",
    "categories":[
      {
        "category_name":"Property, Buildings & Homes"
      },
           
    ],
    "url":" http://www.nyc.gov/apps/311/allServices.htm?requestType=topService&serviceName=Home+Ownership+Kit ",
    "brief_description":" Get a kit to guide you through the process of becoming a homeowner. ",
    "description":"The City offers information about becoming a New York City homeowner, including: Lists of affordable homes that are currently accepting applications The steps of the buying process Down payment assistance Homebuyer education training",
    "description_html":" The City offers information about becoming a New York City homeowner, including:<br /><br /><ul class="dashes"><li>Lists of affordable homes that are currently accepting applications</li><li>The steps of the buying process</li><li>Down payment assistance</li><li>Homebuyer education training</li></ul>",
    "web_actions":[
      {
        "type":"Link",
        "label":"Get information about home ownership.",
        "url":" http://www.nyc.gov/html/hpd/html/buyers/guide.shtml"
      },
      {
        "type":"Link",
        "label":"Download the Home Ownership Kit (PDF).",
        "url":" http://www.nyc.gov/download/311/HPD/homeownership-kit.pdf"
      }
    ]
  }
]

Get Facilities

Facilities include offices, providers, and recreational locations available to the public.

The Get Facility functionality consists of two methods. The first method, “Get Facility List”, retrieves a list of all of the facilities when invoked. The second method, “Get Facility”, retrieves detailed information about the Facility requested when invoked.

Get Facility List

This method retrieves a list of links to all Facilities and a brief description of each Facility. This method takes a category as an optional input. If a category is provided, the list of Facilities returned will be restricted such that only Facilities of the specified category will be included in the response.

URL

http://<content_api_root>/facilities/<category>.<content_type>

Sample URLs

Inputs

category - a category for a Facility. If this argument is supplied then the list of Facilities returned will be restricted to Facilities of this type. The following category values are supported:

Input Value	Encoded Input Value
After School Program	After%20School%20Program
Beach	Beach
Business Solution Center	Business%20Solution%20Center
Child Care Center	Child%20Care%20Center
Clinic	Clinic
Community Board	Community%20Board
Cultural Institution	Cultural%20Institution
DRIE Enrollment Center	DRIE%20Enrollment%20Center
DSNY Garage	DSNY%20Garage
EITC Assistance Center	EITC%20Assistance%20Center
Financial Education Site	Financial%20Education%20Site
Food Provider	Food%20Provider
Food Stamp Center	Food%20Stamp%20Center
Golf	Golf
Green Market	Green%20Market
HomeBase Site	HomeBase%20Site
Hospital	Hospital
Immigrant Service Provider	Immigrant%20Service%20Provider
Jail Release Services	Jail%20Release%20Services
Library	Library
Medicaid Office	Medicaid%20Office
Medicare Drug Counseling	Medicare%20Drug%20Counseling
Municipal Parking Facility	Municipal%20Parking%20Facility
Non-Profit Organization	Non-Profit%20Organization
Nurse Home Visiting Program	Nurse%20Home%20Visiting%20Program
Park	Park
Pool	Pool
Precinct	Precinct
Quit Smoking Clinic	Quit%20Smoking%20Clinic
Recreation Center	Recreation%20Center
School	School
School District	School%20District
Summer Meal Program	Summer%20Meal%20Program
Universal Pre-K	Universal%20Pre-K
Workforce1 Career Center	Workforce1%20Career%20Center
Youth Employment	Youth%20Employment

Response Structure

Field Descriptions

id – the unique identifier for a Facility record
facility_name – the name of a Facility record
expiration – the date that the Facility expires. Expiration will occur at 12:00 AM of the date specified.
brief_description – a short description of the Facility
Note: When requesting a list of all facilities, the facility type (category) will also be included.

Get Facility

This method retrieves detailed information about the Facility requested. Facilities are specified using the ID of the Facility.

URL

http://<content_api_root>/facilities/<facility_id>.<content_type>

Sample URLs

Inputs

facility_id – the Id of the Facility being requested.

Response Structure

Field Descriptions:

id – the unique identifier for a Facility record
facility_name – the name of a Facility
expiration – the date that the Facility expires. Expiration will occur at 12:00 AM of the date specified.
type – the type of office, provider, or recreational Facility
brief_description – a short description of the Facility
description – the detailed description of the Facility
features – characteristics of a Facility
feature_name – the name of a Facility Feature
address – the street address of the Facility
additional_address_information – additional information about the Facility’s location
borough – the borough of the Facility. Possible values are: Manhattan, Brooklyn, The Bronx, Queens, and Staten Island
city – the city the Facility is located in.
state – the state the Facility is located in
zipcode – the zip code of the Facility
displayed_hours – hours of operation for a Facility
lat – the latitude of the Facility (this value may only be compatible with NY State Plane coordinate systems)
long – the longitude of the Facility (this value may only be compatible with NY State Plane coordinate systems)
eligibility_information – requirements for being eligible to use the Facility.

311 Today

The 311 Today feed provides daily status messages regarding Public Schools, Alternate Side Parking, and Garbage/Recycling pick up. Important City announcements based on current events may also be provided through this feed.

311 Today feed is implemented in RSS format. There is no parameter required when the feed is requested.

311 Today Feed

This method retrieves an RSS feed that contains a total of 39 days of 311 Today data (the current day, plus 7 days in the past, and 31 days in the future). No parameter is required as an input. Two extensions modules are used on top of the default RSS format: Content (content:encoded) and Dublic Core (dc:coverage).

URL

http://<content_api_root>/311TodayContent.rss

Sample URLs

http://www.nyc.gov/apps/311/311Today.rss

Inputs

N/A

Response Structure

Field Descriptions

Root level

rss – the beginning of the RSS feed
channel – the beginning of 311 Today RSS feed. There will only be 1 channel for this feed.
title – name of the feed. It will always be NYC 311 Today RSS feed
link – link back to the 311 Online homepage
description – description of the feed

Item level

item – tag that wraps around the date’s content
title – the title for the date’s content
pubDate – publishing date for this story. Note that this is not the date for the content. This is the date the information is being pushed out.
guid – unique ID for the date’s content.
content:encoded – HTML code wrapped for the detail of the content around the CDATA tag. This data is expected to rendered as HTML code.
dc:coverage – describes the event date of the content. It is in yyyy-MM-dd format.

Open311

Wiki

Personal tools

Views

Inquiry v1

Collaboration for an Open311 Standard

Contents

Get Services

Get Service List

URL

Sample URLs

Inputs

Response Structure

Field Descriptions

Get Service

URL

Sample URLs

Inputs

Response Structure

Field Descriptions

Get Facilities

Get Facility List

URL

Sample URLs

Inputs

Response Structure

Field Descriptions

Get Facility

URL

Sample URLs

Inputs

Response Structure

Field Descriptions:

311 Today

311 Today Feed

URL

Sample URLs

Inputs

Response Structure

Field Descriptions

Search

Toolbox

Navigation

Meta

Open311