Introduction

Welcome to the Ohana API documentation. The Ohana API Rails app allows any community to deploy their own instance of the API, and to maintain their own resource directory of human service providers.

We provide code examples for the Shell and Ruby in the dark area to the right, and you can switch the programming language of the examples with the tabs in the top right.

Apps Powered by Ohana API

Ohana Web Search is an open source Rails application that allows you to search for and display information provided by the API in a user-friendly website.

Live Deployments of Ohana API

Currently, there is only one live deployment: in San Mateo County, California. We expect more cities and counties to deploy, and as they do, we will add them to this list. If you have deployed an instance of Ohana API, feel free to add it to this list via a pull request, since this documentation is open source.

San Mateo County, California

• API: http://api.smc-connect.org
• Admin Interface: http://admin.smc-connect.org
• Web Search: SMC-Connect
• Developer Portal: http://developer.smc-connect.org

Current Version

By default, all requests receive version 1 of the API. We encourage you to explicitly request this version via the Accept HTTP header. If you are using our Ruby library, this is automatically done for you.

Accept: application/vnd.ohanapi+json; version=1

Schema

All data is sent and received as JSON. Blank fields are included as null instead of being omitted, and all timestamps are returned in ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ.

Summary Representations

When you fetch a list of locations (via either the locations or the search endpoint), the response includes a subset of the attributes for that location. This is the “summary” representation of the resource. Some attributes are computationally expensive for the API to provide. For performance reasons, the summary representation excludes those attributes. To obtain those attributes, fetch the “detailed” representation.

The location attributes that are excluded from the /search and /locations endpoints are accessibility, email, languages, transportation, mail_address, regular_schedules, and holiday_schedules. The associated contacts and services are also excluded, but the URLs to those representations are provided as contacts_url and services_url. The organization association is also summarized to exclude contacts and phones.

The attributes provided in the summary representation are defined in the Locations Serializer.

The nearby endpoint returns an even smaller JSON representation consisting of the following attributes: id, alternate_name, latitude, longitude, name, slug, address.

Detailed Representations

When you fetch an individual resource, the response typically includes all attributes for that resource. This is the “detailed” representation of the resource. One exception is when fetching an individual location. All of the location's attributes are included in the response, but the organization association is summarized to only include id, alternate_name, name, slug, and url.

Making Requests

# In your shell, you can just pass the correct header with each request
curl "https://ohana-api-demo.herokuapp.com/api" -H "User-Agent: MyClient/1.0.0"

# Provide an API Endpoint
Ohanakapa.configure do |c|
  c.api_endpoint = 'https://ohana-api-demo.herokuapp.com/api'
end

# Fetch all locations
Ohanakapa.locations

If you are using your own client to communicate with Ohana API, please keep the following in mind:

• Always set the User-Agent header. Assuming your client is called "My Client", and its current version is 1.0.0, a good value would be MyClient/1.0.0.

• Always set the Accept header to application/vnd.ohanapi+json; version=1

Note that our Ruby library already does this for you.

Conditional Requests

Most responses return an Etag header. Many responses also return a Last-Modified header. You can use the values of these headers to make subsequent requests to those resources using the If-None-Match and If-Modified-Since headers, respectively. If the resource has not changed, the server will return a 304 Not Modified.

Parameters

Many API methods take optional parameters. For GET requests to the search endpoint, parameters can be passed as an HTTP query string parameter:

$ curl -i "https://ohana-api-demo.herokuapp.com/api/search?keyword=food"

For POST, PATCH, and PUT requests, parameters not included in the URL should be encoded as JSON with a Content-Type of application/json:

$ curl -X PATCH "https://ohana-api-demo.herokuapp.com/api/locations/1/address/1" -d '{"address_1":"New street","city":"Albequerque","state_province":"NM","postal_code":"12345","country":"US"}' -H "X-Api-Token: test" -H "Content-Type: application/json"

Authentication

# Provide an API Token
Ohanakapa.configure do |c|
  c.api_token = 'your_secret_token'
end

# Update location with id: 1
Ohanakapa.update_location(1, { name: 'New Name' })

# With shell, you can just pass the X-Api-Token header with each POST, PATCH, or DELETE request
curl --request PATCH "https://ohana-api-demo.herokuapp.com/api/locations/1?name=Foo" -H "X-Api-Token: your_secret_token"

Note that the Ohana API Rails application already comes with an admin interface, but if you wanted to write your own standalone admin interface, you would need to pass a valid token via the X-Api-Token HTTP header in all POST, PUT, PATCH, and DELETE requests.

If you have access to the API, you would need to set the ADMIN_APP_TOKEN environment variable on the API server to the token sent by the admin app. The easiest way to generate an API token is to register an application in the appropriate developer portal.

If you don't have access to the API, you'll first need to get permission to write to the API from the entity that is maintaining the data. For example, if you want to be able to update San Mateo County data, you would need to contact the Human Services Agency. If you're granted permission, then you can register your application in the San Mateo County Developer portal. Once you obtain your API token, you'll need to ask the API maintainer to set the ADMIN_APP_TOKEN environment variable on the API server to your token.

In most cases, it would not make sense to have multiple apps writing to the API at the same time. Most communities will just use the built-in admin interface, so if a community is already actively using the built-in admin interface, they most likely will not grant write access to an external application.

Cross Origin Resource Sharing

# A sample request sent from a browser hitting http://example.com:
$ curl -i https://ohana-api-demo.herokuapp.com/api/locations -H "Origin: http://example.com"

HTTP/1.1 200 OK
Access-Control-Allow-Origin: http://example.com
Access-Control-Allow-Methods: GET, PUT, PATCH, POST, DELETE
Access-Control-Expose-Headers: Etag, Last-Modified, Link, X-Total-Count
Access-Control-Max-Age: 1728000
Access-Control-Allow-Credentials: true

# A valid CORS preflight request must include the `Access-Control-Request-Method` header
$ curl -i https://ohana-api-demo.herokuapp.com/api/locations -H "Origin: http://example.com" -H "Access-Control-Request-Method: GET" -X OPTIONS

HTTP/1.1 200 OK
Access-Control-Allow-Origin: http://example.com
Access-Control-Allow-Methods: GET, PUT, PATCH, POST, DELETE
Access-Control-Expose-Headers: Etag, Last-Modified, Link, X-Total-Count
Access-Control-Max-Age: 1728000
Access-Control-Allow-Credentials: true

# A valid CORS preflight request can also include the `Allow-Control-Request-Headers` header:
$ curl -i https://ohana-api-demo.herokuapp.com/api/locations -H "Origin: http://example.com" -H "Access-Control-Request-Method: GET" -H "Access-Control-Request-Headers: If-None-Match" -X OPTIONS

HTTP/1.1 200 OK
Access-Control-Allow-Origin: http://example.com
Access-Control-Allow-Methods: GET, PUT, PATCH, POST, DELETE
Access-Control-Expose-Headers: Etag, Last-Modified, Link, X-Total-Count
Access-Control-Max-Age: 1728000
Access-Control-Allow-Credentials: true
Access-Control-Allow-Headers: If-None-Match

The API supports Cross Origin Resource Sharing (CORS) for AJAX requests. You can read the CORS W3C working draft for more details.

The API supports the following endpoints for CORS requests:

• /organizations
• /locations
• /search

The following methods are allowed:

• GET, PUT, PATCH, POST, DELETE

The following additional headers are exposed:

• Etag
• Last-Modified
• Link
• X-Total-Count

View sample requests and responses on the right in the Shell tab.

View the source code.

Root Endpoint

Sending a GET request to the root endpoint will return all endpoint categories that the API supports.

GET https://ohana-api-demo.herokuapp.com/api

The root endpoint returns JSON structured like this:

{
  "organizations_url": "https://ohana-api-demo.herokuapp.com/api/organizations{?page,per_page}",
  "organization_url": "https://ohana-api-demo.herokuapp.com/api/organizations/{organization}",
  "organization_locations_url": "https://ohana-api-demo.herokuapp.com/api/organizations/{organization}/locations{?page,per_page}",
  "locations_url": "https://ohana-api-demo.herokuapp.com/api/locations{?page,per_page}",
  "location_url": "https://ohana-api-demo.herokuapp.com/api/locations/{location}",
  "location_search_url": "https://ohana-api-demo.herokuapp.com/api/search{?category,email,keyword,language,lat_lng,org_name,radius,service_area,status,page,per_page}"
}

All URLs are expected to be proper RFC 6570 URI templates.

You can then expand these templates using something like the uri_template Ruby gem. See example code in the Ruby tab on the right.

# Example usage of the uri_template gem
>> tmpl = URITemplate.new('/search{?keyword,location,language}')
>> tmpl.expand
=> "/search"

>> tmpl.expand keyword: 'food'
=> "/search?keyword=food"

>> tmpl.expand keyword: 'food', location: '94403'
=> "/search?keyword=food&location=94403"

Organizations

Get all organizations

# Provide an API Endpoint
Ohanakapa.configure do |c|
  c.api_endpoint = 'https://ohana-api-demo.herokuapp.com/api'
end

# Fetch all organizations
Ohanakapa.organizations

curl "https://ohana-api-demo.herokuapp.com/api/organizations" -H "User-Agent: MyClient/1.0.0"

The above command returns JSON structured like this:

[
  {
    "id": 7,
    "accreditations": [],
    "alternate_name": null,
    "date_incorporated": null,
    "description": "An organization created for testing purposes.",
    "email": null,
    "funding_sources": [],
    "licenses": [],
    "name": "Admin Test Org",
    "slug": "admin-test-org",
    "website": null,
    "url": "http://ohana-api-demo.herokuapp.com/api/organizations/admin-test-org",
    "locations_url": "http://ohana-api-demo.herokuapp.com/api/organizations/admin-test-org/locations",
    "contacts": [],
    "phones": []
  },
  {
    "id": 6,
    "accreditations": [],
    "alternate_name": null,
    "date_incorporated": null,
    "description": "An organization created for testing purposes.",
    "email": null,
    "funding_sources": [],
    "licenses": [],
    "name": "Fake Org",
    "slug": "fake-org",
    "website": null,
    "url": "http://ohana-api-demo.herokuapp.com/api/organizations/fake-org",
    "locations_url": "http://ohana-api-demo.herokuapp.com/api/organizations/fake-org/locations",
    "contacts": [],
    "phones": []
  }
]

This endpoint retrieves all organizations.

HTTP Request

GET https://ohana-api-demo.herokuapp.com/api/organizations

Note that the URL above is just an example for the demo instance. To access an API that serves a particular region, you would need to look up the appropriate endpoint. All known API deployments are listed in the deployments section at the top of this page.

URL Query Parameters

Parameter	Default	Description
page	1	The particular page of results.
per_page	30	Amount of organizations to return per page, up to 100.

Get a specific organization

# Find an organization by id
Ohanakapa.organization(1)

# Find an organization by slug
Ohanakapa.organization('peninsula-family-service')

# Find an organization by slug
curl "https://ohana-api-demo.herokuapp.com/api/organizations/peninsula-family-service"

# Find an organization by id
curl "https://ohana-api-demo.herokuapp.com/api/organizations/1"

When successful, the above command returns a 200 HTTP status code and JSON structured like this:

{
  "id": 1,
  "accreditations": [],
  "alternate_name": null,
  "date_incorporated": null,
  "description":"Peninsula Family Service strengthens the community by providing children, families, and older adults the support and tools to realize their full potential and lead healthy, stable lives.",
  "email": null,
  "funding_sources": [],
  "licenses": [],
  "name": "Peninsula Family Service",
  "slug": "peninsula-family-service",
  "website": null,
  "url": "http://ohana-api-demo.herokuapp.com/api/organizations/peninsula-family-service",
  "locations_url": "http://ohana-api-demo.herokuapp.com/api/organizations/peninsula-family-service/locations",
  "contacts":[
    {
      "department":"Operations",
      "email":"e.feeney@foobar.org",
      "id":32,
      "name":"Elizabeth Feeney",
      "title":"CEO",
      "phones":[
        {
          "id":54,
          "department":"Operations",
          "extension":null,
          "number":"703-444-1234",
          "number_type":"fax",
          "vanity_number":null
        },
        {
          "id":55,
          "department":"Operations",
          "extension":"101",
          "number":"650-555-1212",
          "number_type":"voice",
          "vanity_number":null
        }
      ]
    }
  ],
  "phones":[
    {
      "id":53,
      "department":"Operations",
      "extension":"101",
      "number":"123-456-7890",
      "number_type":"voice",
      "vanity_number":null
    }
  ]
}

This endpoint retrieves a specific organization.

HTTP Request

GET https://ohana-api-demo.herokuapp.com/api/organizations/peninsula-family-service

or

GET https://ohana-api-demo.herokuapp.com/api/organizations/1

URL Parameters

Parameter	Description
id	The ID or slug of the organization to retrieve

Create a new organization

# Create a new organization
Ohanakapa.post('organizations', query: { name: 'New Organization' })

curl -X POST "https://ohana-api-demo.herokuapp.com/api/organizations -d '{"name":"New Organization","description":"New description"}' -H "X-Api-Token: your_token" -H "Content-Type: application/json"

When successful, the above command returns a 201 HTTP status code and JSON structured like this:

{
  "id": 1,
  "accreditations": [],
  "alternate_name": null,
  "date_incorporated": null,
  "description": "Test description",
  "email": null,
  "funding_sources": [],
  "licenses": [],
  "name": "New Organization",
  "slug": "new-organization",
  "website": null,
  "url": "https://ohana-api-demo.herokuapp.com/api/organizations/new-organization",
  "locations_url": "https://ohana-api-demo.herokuapp.com/api/organizations/new-organization/locations",
  "contacts": [],
  "phones": []
}

This endpoint creates a new organization.

HTTP Request

POST https://ohana-api-demo.herokuapp.com/api/organizations

JSON Parameters

Name	Type	Requirement	Details
accreditations	Array of Strings	optional	A list of accreditations an organization has received.
alternate_name	String	optional	Another name this organization might be known by.
date_incorporated	Date	optional	The date this organization was incorporated.
description	String	required	A description of what the organization does.
email	String	optional	The organization's primary email.
funding_sources	Array of Strings	optional	A list of sources of funds for an organization.
legal_status	String	optional	The conditions an organization is operating under; e.g. non-profit, private corporation or a government organization.
licenses	Array of Strings	optional	A list of licenses an organization has obtained to operate legally.
name	String	required	Name of the organization
tax_id	String	optional	Tax identifier, such as Federal Employer Identification Number.
tax_status	String	optional	Internal Revenue Service tax designation, such as 501(c)(3) for tax-exempt organizations.
website	String	optional	The organization's website

Update an existing organization

# Update organization whose id is 1
Ohanakapa.patch('organizations/1', query: { name: 'Updated Name' })

curl -X PATCH "https://ohana-api-demo.herokuapp.com/api/organizations/1/address/1" -d '{"name":"Updated Name"}' -H "X-Api-Token: test" -H "Content-Type: application/json"

When successful, the above command returns a 200 HTTP status code and JSON structured like this:

{
  "id": 1,
  "accreditations": [],
  "alternate_name": null,
  "date_incorporated": null,
  "description": "Test description",
  "email": null,
  "funding_sources": [],
  "licenses": [],
  "name": "Updated Name",
  "slug": "updated-name",
  "website": null,
  "url": "https://ohana-api-demo.herokuapp.com/api/organizations/admin-test-org",
  "locations_url": "https://ohana-api-demo.herokuapp.com/api/organizations/admin-test-org/locations",
  "contacts": [],
  "phones": []
}

This endpoint updates an existing organization.

HTTP Request

PATCH https://ohana-api-demo.herokuapp.com/api/organizations/1

JSON Parameters

Name	Type	Requirement	Details
accreditations	Array of Strings	optional	A list of accreditations an organization has received.
alternate_name	String	optional	Another name this organization might be known by.
date_incorporated	Date	optional	The date this organization was incorporated.
description	String	required	A description of what the organization does.
email	String	optional	The organization's primary email.
funding_sources	Array of Strings	optional	A list of sources of funds for an organization.
legal_status	String	optional	The conditions an organization is operating under; e.g. non-profit, private corporation or a government organization.
licenses	Array of Strings	optional	A list of licenses an organization has obtained to operate legally.
name	String	required	Name of the organization
tax_id	String	optional	Tax identifier, such as Federal Employer Identification Number.
tax_status	String	optional	Internal Revenue Service tax designation, such as 501(c)(3) for tax-exempt organizations.
website	String	optional	The organization's website

Delete an existing organization

# Delete organization with id 1
Ohanakapa.delete('organizations/1')

curl --request DELETE "https://ohana-api-demo.herokuapp.com/api/organizations/1" -H "X-Api-Token: your_secret_token"

When successful, the above command returns a 204 HTTP status code with an empty body.

This endpoint deletes an existing organization.

HTTP Request

DELETE https://ohana-api-demo.herokuapp.com/api/organizations/:organization_id

Organization Locations

Get all locations belonging to an organization

# Provide an API Endpoint
Ohanakapa.configure do |c|
  c.api_endpoint = 'https://ohana-api-demo.herokuapp.com/api'
end

# Fetch all locations belonging to the organization with id 1
Ohanakapa.get('organizations/1/locations')

curl "https://ohana-api-demo.herokuapp.com/api/organizations/1/locations" -H "User-Agent: MyClient/1.0.0"

The above command returns JSON structured like this:

[
  {
    "id": 31,
    "active": true,
    "admin_emails": [ ],
    "coordinates": [
      -122.4456187,
      37.7517064
    ],
    "description": "Testing adding a new location",
    "latitude": 37.7517064,
    "longitude": -122.4456187,
    "name": "New location test",
    "short_desc": null,
    "slug": "new-location-test",
    "website": null,
    "updated_at": "2014-09-10T08:21:14.853-07:00",
    "contacts_url": "https://ohana-api-demo.herokuapp.com/api/locations/new-location-test/contacts",
    "services_url": "https://ohana-api-demo.herokuapp.com/api/locations/new-location-test/services",
    "url": "https://ohana-api-demo.herokuapp.com/api/locations/new-location-test",
    "address": {
      "id": 28,
      "address_1": "1290 Ridder Park Drive",
      "address_2": null,
      "city": "San Francisco",
      "state_province": "CA",
      "postal_code": "94103"
    },
    "organization": {
      "id": 8,
      "accreditations": [],
      "alternate_name": null,
      "date_incorporated": null,
      "description": "Test description",
      "email": null,
      "funding_sources": [],
      "licenses": [],
      "name": "Admin Test Org",
      "slug": "admin-test-org",
      "website": null,
      "url": "https://ohana-api-demo.herokuapp.com/api/organizations/admin-test-org",
      "locations_url": "https://ohana-api-demo.herokuapp.com/api/organizations/admin-test-org/locations"
    },
    "phones": [ ]
  },
  {
    "id": 30,
    "active": true,
    "admin_emails": [ ],
    "coordinates": [
      -122.4136494,
      37.7756408
    ],
    "description": "Location with no service",
    "latitude": 37.7756408,
    "longitude": -122.4136494,
    "name": "Location with no service",
    "short_desc": null,
    "slug": "location-with-no-service",
    "website": null,
    "updated_at": "2014-09-10T08:21:14.848-07:00",
    "contacts_url": "https://ohana-api-demo.herokuapp.com/api/locations/location-with-no-service/contacts",
    "services_url": "https://ohana-api-demo.herokuapp.com/api/locations/location-with-no-service/services",
    "url": "https://ohana-api-demo.herokuapp.com/api/locations/location-with-no-service",
    "address": {
      "id": 27,
      "address_1": "155 9th St",
      "address_2": null,
      "city": "San Francisco",
      "state_province": "CA",
      "postal_code": "94103"
    },
    "organization": {
      "id": 8,
      "accreditations": [],
      "alternate_name": null,
      "date_incorporated": null,
      "description": "Test description",
      "email": null,
      "funding_sources": [],
      "licenses": [],
      "name": "Admin Test Org",
      "slug": "admin-test-org",
      "website": null,
      "url": "https://ohana-api-demo.herokuapp.com/api/organizations/admin-test-org",
      "locations_url": "https://ohana-api-demo.herokuapp.com/api/organizations/admin-test-org/locations"
    },
    "phones": [ ]
  }
]

This endpoint retrieves all locations that belong to a particular organization.

HTTP Request

GET https://ohana-api-demo.herokuapp.com/api/organizations/:id/locations

Note that the URL above is just an example for the demo instance. To access an API that serves a particular region, you would need to look up the appropriate endpoint. All known API deployments are listed in the deployments section at the top of this page.

URL Query Parameters

Parameter	Default	Description
page	1	The particular page of results.
per_page	30	Amount of locations to return per page, up to 100.

Locations

Get all locations

# Provide an API Endpoint
Ohanakapa.configure do |c|
  c.api_endpoint = 'https://ohana-api-demo.herokuapp.com/api'
end

# Fetch all locations
Ohanakapa.locations

curl "https://ohana-api-demo.herokuapp.com/api/locations" -H "User-Agent: MyClient/1.0.0"

The above command returns JSON structured like this:

[
  {
    "id": 31,
    "admin_emails": [ ],
    "coordinates": [
      -122.4456187,
      37.7517064
    ],
    "description": "Testing adding a new location",
    "latitude": 37.7517064,
    "longitude": -122.4456187,
    "name": "New location test",
    "short_desc": null,
    "slug": "new-location-test",
    "updated_at": "2014-09-10T08:21:14.853-07:00",
    "website": null,
    "contacts_url": "https://ohana-api-demo.herokuapp.com/api/locations/new-location-test/contacts",
    "services_url": "https://ohana-api-demo.herokuapp.com/api/locations/new-location-test/services",
    "url": "https://ohana-api-demo.herokuapp.com/api/locations/new-location-test",
    "address": {
      "id": 28,
      "address_1": "1290 Ridder Park Drive",
      "address_2": null,
      "city": "San Francisco",
      "state_province": "CA",
      "postal_code": "94103"
    },
    "organization": {
      "id": 8,
      "accreditations": [],
      "alternate_name": null,
      "date_incorporated": null,
      "description": "Test description",
      "email": null,
      "funding_sources": [],
      "licenses": [],
      "name": "Admin Test Org",
      "slug": "admin-test-org",
      "website": null,
      "url": "https://ohana-api-demo.herokuapp.com/api/organizations/admin-test-org",
      "locations_url": "https://ohana-api-demo.herokuapp.com/api/organizations/admin-test-org/locations"
    },
    "phones": [ ]
  },
  {
    "id": 30,
    "admin_emails": [ ],
    "coordinates": [
      -122.4136494,
      37.7756408
    ],
    "description": "Location with no service",
    "latitude": 37.7756408,
    "longitude": -122.4136494,
    "name": "Location with no service",
    "short_desc": null,
    "slug": "location-with-no-service",
    "updated_at": "2014-09-10T08:21:14.848-07:00",
    "website": null,
    "contacts_url": "https://ohana-api-demo.herokuapp.com/api/locations/location-with-no-service/contacts",
    "faxes_url": "https://ohana-api-demo.herokuapp.com/api/locations/location-with-no-service/faxes",
    "services_url": "https://ohana-api-demo.herokuapp.com/api/locations/location-with-no-service/services",
    "url": "https://ohana-api-demo.herokuapp.com/api/locations/location-with-no-service",
    "address": {
      "id": 27,
      "address_1": "155 9th St",
      "address_2": null,
      "city": "San Francisco",
      "state_province": "CA",
      "postal_code": "94103"
    },
    "organization": {
      "id": 8,
      "accreditations": [],
      "alternate_name": null,
      "date_incorporated": null,
      "description": "Test description",
      "email": null,
      "funding_sources": [],
      "licenses": [],
      "name": "Admin Test Org",
      "slug": "admin-test-org",
      "website": null,
      "url": "https://ohana-api-demo.herokuapp.com/api/organizations/admin-test-org",
      "locations_url": "https://ohana-api-demo.herokuapp.com/api/organizations/admin-test-org/locations"
    },
    "phones": [ ]
  }
]

This endpoint retrieves all locations.

HTTP Request

GET https://ohana-api-demo.herokuapp.com/api/locations

Note that the URL above is just an example for the demo instance. To access an API that serves a particular region, you would need to look up the appropriate endpoint. All known API deployments are listed in the deployments section at the top of this page.

URL Query Parameters

Parameter	Default	Description
page	1	The particular page of results.
per_page	30	Amount of locations to return per page, up to 100.

Get a specific location

# Find a location by id
Ohanakapa.location(1)

# Find a location by slug
Ohanakapa.location('redwood-shores-branch')

# Find a location by slug
curl "https://ohana-api-demo.herokuapp.com/api/locations/redwood-shores-branch"

# Find a location by id
curl "https://ohana-api-demo.herokuapp.com/api/locations/1"

When successful, the above command returns a 200 HTTP status code and JSON structured like this:

{
  "id": 14,
  "active": true,
  "accessibility": [ ],
  "admin_emails": [ ],
  "alternate_name": null,
  "coordinates": [
    -122.2586432,
    37.5304228
  ],
  "description": "Provides general reading materials, including large-type books, videos, music cassettes and CDs, and books on tape. Offers children's programs and a Summer Reading Club. Meeting room is available to nonprofit groups. Participates in the Peninsula Library System.",
  "email": null,
  "languages": [ ],
  "latitude": 37.5304228,
  "longitude": -122.2586432,
  "name": "Redwood Shores Branch",
  "short_desc": "Provides general reading materials and reference services.",
  "slug": "redwood-shores-branch",
  "transportation": null,
  "website": "http://www.redwoodcity.org/library",
  "updated_at": "2014-09-09T07:54:08.641-07:00",
  "url": "https://ohana-api-demo.herokuapp.com/api/locations/redwood-shores-branch",
  "address": {
    "id": 14,
    "address_1": "399 Marine Parkway",
    "address_2": null,
    "city": "Redwood City",
    "state_province": "CA",
    "postal_code": "94065"
  },
  "contacts": [
    {
      "department": null,
      "email": null,
      "id": 22,
      "name": "Dave Genesy",
      "title": "Library Director",
      "phones": []
    }
  ],
  "mail_address": {
    "id": 14,
    "attention": "Redwood Shores Branch",
    "address_1": "399 Marine Parkway",
    "address_2": null,
    "city": "Redwood City",
    "state_province": "CA",
    "postal_code": "94065"
  },
  "phones": [
    {
      "id": 15,
      "department": null,
      "extension": null,
      "number": "650 780-5740",
      "number_type": "voice",
      "vanity_number": null
    }
  ],
  "services": [
    {
      "id": 15,
      "accepted_payments": [],
      "alternate_name": null,
      "audience": null,
      "description": null,
      "eligibility": "Resident of California to obtain a library card",
      "email": null,
      "fees": "None.",
      "funding_sources": [
        "City"
      ],
      "application_process": "Walk in. Proof of California residency required to receive a library card.",
      "keywords": [
        "EDUCATION SERVICES",
        "Library",
        "Libraries",
        "Public Libraries"
      ],
      "languages": [],
      "name": null,
      "required_documents": [],
      "service_areas": [
        "San Mateo County"
      ],
      "status": "active",
      "website": null,
      "wait_time": "No wait.",
      "updated_at": "2014-04-16T19:51:28.610-07:00",
      "categories": [],
      "contacts": [],
      "phones": [],
      "regular_schedules":[
        {
          "weekday":"Monday",
          "opens_at":"2000-01-01T08:00:00.000Z",
          "closes_at":"2000-01-01T12:00:00.000Z"
        },
        {
          "weekday":"Monday",
          "opens_at":"2000-01-01T14:00:00.000Z",
          "closes_at":"2000-01-01T16:00:00.000Z"
        },
        {
          "weekday":"Wednesday",
          "opens_at":"2000-01-01T10:00:00.000Z",
          "closes_at":"2000-01-01T15:00:00.000Z"
        }
      ],
      "holiday_schedules":[]
    }
  ],
  "regular_schedules":[
    {
      "weekday":"Monday",
      "opens_at":"2000-01-01T08:00:00.000Z",
      "closes_at":"2000-01-01T17:00:00.000Z"
    },
    {
      "weekday":"Tuesday",
      "opens_at":"2000-01-01T08:00:00.000Z",
      "closes_at":"2000-01-01T17:00:00.000Z"
    },
    {
      "weekday":"Wednesday",
      "opens_at":"2000-01-01T08:00:00.000Z",
      "closes_at":"2000-01-01T17:00:00.000Z"
    },
    {
      "weekday":"Thursday",
      "opens_at":"2000-01-01T08:00:00.000Z",
      "closes_at":"2000-01-01T17:00:00.000Z"
    },
    {
      "weekday":"Friday",
      "opens_at":"2000-01-01T08:00:00.000Z",
      "closes_at":"2000-01-01T17:00:00.000Z"
    },
    {
      "weekday":"Saturday",
      "opens_at":"2000-01-01T10:00:00.000Z",
      "closes_at":"2000-01-01T18:00:00.000Z"
    },
    {
      "weekday":"Sunday",
      "opens_at":"2000-01-01T11:00:00.000Z",
      "closes_at":"2000-01-01T17:00:00.000Z"
    }
  ],
  "holiday_schedules":[
    {
      "closed":true,
      "start_date":"0001-01-01",
      "end_date":"0001-01-01",
      "opens_at":null,
      "closes_at":null
    },
    {
      "closed":false,
      "start_date":"0001-12-24",
      "end_date":"0001-12-24",
      "opens_at":"2000-01-01T10:00:00.000Z",
      "closes_at":"2000-01-01T16:00:00.000Z"
    },
    {
      "closed":true,
      "start_date":"0001-06-01",
      "end_date":"0001-09-01",
      "opens_at":null,
      "closes_at":null
    }
  ],
  "organization": {
    "id": 4,
    "alternate_name": null,
    "name": "Redwood City Public Library",
    "slug": "redwood-city-public-library",
    "url": "https://ohana-api-demo.herokuapp.com/api/organizations/redwood-city-public-library",
  }
}

This endpoint retrieves a specific location.

HTTP Request

GET https://ohana-api-demo.herokuapp.com/api/locations/1

or

GET https://ohana-api-demo.herokuapp.com/api/locations/redwood-shores-branch

Note about location status

For clients that display information about a particular Location, it might make sense to display a warning or other message if the Location currently doesn’t have any active services. You can determine if that’s the case by checking if the Location’s JSON contains an active attribute set to false.

Note about holiday schedules

A location can have one more holiday schedules that describe whether or not the location is closed on a particular day of the year, or during a range of days. If the location is not closed, it will also provide opens_at and closes_at fields to describe the special holiday hours.

Although the start_date and end_date fields are provided as a Date type with day, month, and year details, make sure to only extract the day and month because the actual year is not guaranteed to be the current year. In addition, make sure you don't extract the weekday name from this field because it's not guaranteed to be correct. The only important information from this field is the month and the day of the month, such as December 24.

For a Ruby on Rails example of how you would display Regular and Holiday Schedules on website in a user-friendly manner, check out the Ohana Web Search source code.

URL Parameters

Parameter	Description
id	The ID or slug of the location to retrieve

Create a new location

# Create a new location for organization with id 1
Ohanakapa.post("organizations/1/locations",
  query: { name: 'New Location', description: 'New description' })

curl -X POST "https://ohana-api-demo.herokuapp.com/api/organizations/1/locations" -d '{"name":"New Location","description":"New description"}' -H "X-Api-Token: your_token" -H "Content-Type: application/json"

When successful, the above command returns a 201 HTTP status code and JSON structured like this:

{
  "id": 14,
  "name": "New Location",
  "slug": "new-location"
}

This endpoint creates a new location for the specified organization.

HTTP Request

POST https://ohana-api-demo.herokuapp.com/api/organizations/:organization_id/locations

JSON Parameters

Name	Type	Requirement	Details
accessibility	array of strings	optional	Accessibility options available at the location. Accepted values are cd, deaf_interpreter, disabled_parking, elevator, ramp, restroom, tape_braille, tty, wheelchair, and wheelchair_van.
address_attributes	object	required unless the location is marked as virtual	Physical address of location. See the Address section for the columns in that table.
admin_emails	array of strings	optional	Email address for a person allowed to administer the location (via the Ohana API Admin interface for example).
alternate_name	String	optional	Another name this location might be known by.
latitude	float	optional	Latitude portion of the location's coordinates. Note that the app automatically geocodes addresses if the data doesn't include coordinates
longitude	float	optional	Longitude portion of the location's coordinates. Note that the app automatically geocodes addresses if the data doesn't include coordinates
description	string	required	Description of services provided at the location
email	string	optional	General Email address for location. Emails that belong to contacts should go in the Contact object.
languages	array of strings	optional	Languages spoken at the location
name	string	required	Name of the location
short_desc	string	optional	Succinct description of services provided at the location.
transportation	string	optional	Public transportation options near the location
website	string	optional	The location's website. Must include "http://" or "https://"
virtual	boolean	required if the location does not have a physical address	Whether or not the location has a physical address. If false, it must have an address associated with it. The default value is false.

Update an existing location

# Update location whose id is 1
Ohanakapa.update_location(1, { name: 'Updated Name' })

curl -X PATCH "https://ohana-api-demo.herokuapp.com/api/locations/1" -d '{"name":"Updated name"}' -H "X-Api-Token: test" -H "Content-Type: application/json"

When successful, the above command returns a 200 HTTP status code and JSON structured like this:

{
  "id": 14,
  "active": true,
  "accessibility": [ ],
  "admin_emails": [ ],
  "alternate_name": null,
  "coordinates": [
    -122.2586432,
    37.5304228
  ],
  "description": "Provides general reading materials, including large-type books, videos, music cassettes and CDs, and books on tape. Offers children's programs and a Summer Reading Club. Meeting room is available to nonprofit groups. Participates in the Peninsula Library System.",
  "email": null,
  "languages": [ ],
  "latitude": 37.5304228,
  "longitude": -122.2586432,
  "name": "Updated Name",
  "short_desc": "Provides general reading materials and reference services.",
  "slug": "redwood-shores-branch",
  "transportation": null,
  "website": "http://www.redwoodcity.org/library",
  "updated_at": "2014-09-09T07:54:08.641-07:00",
  "url": "https://ohana-api-demo.herokuapp.com/api/locations/redwood-shores-branch",
  "address": {
    "id": 14,
    "address_1": "399 Marine Parkway",
    "address_2": null,
    "city": "Redwood City",
    "state_province": "CA",
    "postal_code": "94065"
  },
  "contacts": [
    {
      "department": null,
      "email": null,
      "id": 22,
      "name": "Dave Genesy",
      "title": "Library Director",
      "phones": []
    }
  ],
  "mail_address": {
    "id": 14,
    "attention": "Redwood Shores Branch",
    "address_1": "399 Marine Parkway",
    "address_2": null,
    "city": "Redwood City",
    "state_province": "CA",
    "postal_code": "94065"
  },
  "phones": [
    {
      "id": 15,
      "department": null,
      "extension": null,
      "number": "650 780-5740",
      "number_type": "voice",
      "vanity_number": null
    }
  ],
  "services": [
    {
      "id": 15,
      "accepted_payments": [],
      "alternate_name": null,
      "audience": null,
      "description": null,
      "eligibility": "Resident of California to obtain a library card",
      "email": null,
      "fees": "None.",
      "funding_sources": [
        "City"
      ],
      "application_process": "Walk in. Proof of California residency required to receive a library card.",
      "keywords": [
        "EDUCATION SERVICES",
        "Library",
        "Libraries",
        "Public Libraries"
      ],
      "languages": [],
      "name": null,
      "required_documents": [],
      "service_areas": [
        "San Mateo County"
      ],
      "status": "active",
      "website": null,
      "wait_time": "No wait.",
      "updated_at": "2014-04-16T19:51:28.610-07:00",
      "categories": [ ],
      "contacts": [],
      "phones": [],
      "regular_schedules":[],
      "holiday_schedules":[]
    }
  ],
  "regular_schedules":[
    {
      "weekday":"Monday",
      "opens_at":"2000-01-01T08:00:00.000Z",
      "closes_at":"2000-01-01T17:00:00.000Z"
    },
    {
      "weekday":"Tuesday",
      "opens_at":"2000-01-01T08:00:00.000Z",
      "closes_at":"2000-01-01T17:00:00.000Z"
    },
    {
      "weekday":"Wednesday",
      "opens_at":"2000-01-01T08:00:00.000Z",
      "closes_at":"2000-01-01T17:00:00.000Z"
    },
    {
      "weekday":"Thursday",
      "opens_at":"2000-01-01T08:00:00.000Z",
      "closes_at":"2000-01-01T17:00:00.000Z"
    },
    {
      "weekday":"Friday",
      "opens_at":"2000-01-01T08:00:00.000Z",
      "closes_at":"2000-01-01T17:00:00.000Z"
    },
    {
      "weekday":"Saturday",
      "opens_at":"2000-01-01T10:00:00.000Z",
      "closes_at":"2000-01-01T18:00:00.000Z"
    },
    {
      "weekday":"Sunday",
      "opens_at":"2000-01-01T11:00:00.000Z",
      "closes_at":"2000-01-01T17:00:00.000Z"
    }
  ],
  "holiday_schedules":[
    {
      "closed":true,
      "start_date":"0001-01-01",
      "end_date":"0001-01-01",
      "opens_at":null,
      "closes_at":null
    },
    {
      "closed":false,
      "start_date":"0001-12-24",
      "end_date":"0001-12-24",
      "opens_at":"2000-01-01T10:00:00.000Z",
      "closes_at":"2000-01-01T16:00:00.000Z"
    },
    {
      "closed":true,
      "start_date":"0001-06-01",
      "end_date":"0001-09-01",
      "opens_at":null,
      "closes_at":null
    }
  ],
  "organization": {
    "id": 8,
    "alternate_name": null,
    "name": "Admin Test Org",
    "slug": "admin-test-org",
    "url": "https://ohana-api-demo.herokuapp.com/api/organizations/admin-test-org",
  }
}

This endpoint updates an existing location.

HTTP Request

PATCH https://ohana-api-demo.herokuapp.com/api/locations/1

JSON Parameters

Name	Type	Requirement	Details
accessibility	array of strings	optional	Accessibility options available at the location. Accepted values are cd, deaf_interpreter, disabled_parking, elevator, ramp, restroom, tape_braille, tty, wheelchair, and wheelchair_van.
admin_emails	array of strings	optional	Email address for a person allowed to administer the location (via the Ohana API Admin interface for example).
alternate_name	String	optional	Another name this location might be known by.
latitude	float	optional	Latitude portion of the location's coordinates. Note that the app automatically geocodes addresses if the data doesn't include coordinates
longitude	float	optional	Longitude portion of the location's coordinates. Note that the app automatically geocodes addresses if the data doesn't include coordinates
description	string	required	Description of services provided at the location
email	string	optional	General Email address for location. Emails that belong to contacts should go in the Contact object.
languages	array of strings	optional	Languages spoken at the location
name	string	required	Name of the location
short_desc	string	optional	Succinct description of services provided at the location.
transportation	string	optional	Public transportation options near the location
website	string	optional	The location's website. Must include "http://" or "https://"
virtual	boolean	required if the location does not have a physical address	Whether or not the location has a physical address. If false, it must have an address associated with it. The default value is false.

Delete an existing location

# Delete location with id 1
Ohanakapa.delete('locations/1')

curl --request DELETE "https://ohana-api-demo.herokuapp.com/api/locations/1" -H "X-Api-Token: your_secret_token"

When successful, the above command returns a 204 HTTP status code with an empty body.

This endpoint deletes an existing location.

HTTP Request

DELETE https://ohana-api-demo.herokuapp.com/api/locations/:location_id

Address

Create a new address

# Create an address for location with id 1
Ohanakapa.post('locations/1/address/', { address_1: 'New Street', city: 'Albequerque', state_province: 'NM', postal_code: '12345', country: 'US' })

curl -X POST "https://ohana-api-demo.herokuapp.com/api/locations/1/address" -d '{"address_1":"New street","city":"Albequerque","state_province":"NM","postal_code":"12345", "country":"US"}' -H "X-Api-Token: your_token" -H "Content-Type: application/json"

When successful, the above command returns a 201 HTTP status code and JSON structured like this:

{
  "id": 2,
  "address_1": "New Street",
  "address_2": null,
  "city": "Albequerque",
  "state_province": "NM",
  "postal_code": "12345"
}

This endpoint creates a new address for the specified location.

HTTP Request

POST https://ohana-api-demo.herokuapp.com/api/locations/:location_id/address

JSON Parameters

Name	Type	Requirement	Detail
address_1	string	required	The primary part of the Street Address
address_2	string	optional	The secondary part of the Street Address, such as the Suite, Room, or Floor number
city	string	required	The City name
state_province	string	required	2-letter US state_province abbreviation
postal_code	string	required	A valid postal code. Note that the API currently assumes this will be a US 5 or 9-digit ZIP code. 9-digit ZIP codes are separated with a dash, like this: 94025-9881. If you are using non-US data, you will need to replace the postal code validation with your own.
country	string	required	2-letter ISO 3361-1 country code

Update an existing address

# Update address with id 1 for location with id 1
Ohanakapa.patch('locations/1/address/1', { street: 'Updated Street' })

curl -X PATCH "https://ohana-api-demo.herokuapp.com/api/locations/1/address/1" -d '{"address_1":"Updated Street"}' -H "X-Api-Token: test" -H "Content-Type: application/json"

When successful, the above command returns a 200 HTTP status code and JSON structured like this:

{
  "id": 1,
  "address_1": "Updated Street",
  "address_2": null,
  "city": "Redwood City",
  "state_province": "CA",
  "postal_code": "94065"
}

This endpoint updates an existing address for the specified location.

HTTP Request

PATCH https://ohana-api-demo.herokuapp.com/api/locations/:location_id/address/:address_id

JSON Parameters

Name	Type	Requirement	Detail
address_1	string	required	The primary part of the Street Address
address_2	string	optional	The secondary part of the Street Address, such as the Suite, Room, or Floor number
city	string	required	The City name
state_province	string	required	2-letter US state_province abbreviation
postal_code	string	required	A valid postal code. Note that the API currently assumes this will be a US 5 or 9-digit ZIP code. 9-digit ZIP codes are separated with a dash, like this: 94025-9881. If you are using non-US data, you will need to replace the postal code validation with your own.
country	string	required	2-letter ISO 3361-1 country code

Delete an existing address

# Delete address with id 1 for location with id 1
Ohanakapa.delete('locations/1/address/1')

curl --request DELETE "https://ohana-api-demo.herokuapp.com/api/locations/1/address/1" -H "X-Api-Token: your_secret_token"

When successful, the above command returns a 204 HTTP status code with an empty body.

This endpoint deletes an existing address.

HTTP Request

DELETE https://ohana-api-demo.herokuapp.com/api/locations/:location_id/address/:address_id

Mail Address

Create a new mail address

# Create a mail address for location with id 1
Ohanakapa.post('locations/1/mail_address/', { address_1: 'New Street', city: 'Albequerque', state_province: 'NM', postal_code: '12345', country: 'US' })

curl -X POST "https://ohana-api-demo.herokuapp.com/api/locations/1/mail_address" -d '{"address_1":"New street","city":"Albequerque","state_province":"NM","postal_code":"12345", "country":"US"}' -H "X-Api-Token: your_token" -H "Content-Type: application/json"

When successful, the above command returns a 201 HTTP status code and JSON structured like this:

{
  "id": 2,
  "attention": null,
  "address_1": "New Street",
  "address_2": null,
  "city": "Albequerque",
  "state_province": "NM",
  "postal_code": "12345"
}

This endpoint creates a new mail address for the specified location.

HTTP Request

POST https://ohana-api-demo.herokuapp.com/api/locations/:location_id/mail_address

JSON Parameters

Name	Type	Requirement	Detail
attention	string	optional	Any person the letter might be addressed to.
address_1	string	required	The primary part of the Street Address or P.O. Box number.
address_2	string	optional	The secondary part of the Street Address, such as the Suite, Room, or Floor number
city	string	required	The City name
state_province	string	required	2-letter US state_province abbreviation
postal_code	string	required	A valid postal code. Note that the API currently assumes this will be a US 5 or 9-digit ZIP code. 9-digit ZIP codes are separated with a dash, like this: 94025-9881. If you are using non-US data, you will need to replace the postal code validation with your own.
country	string	required	2-letter ISO 3361-1 country code

Update an existing mail address

# Update mail address with id 1 for location with id 1
Ohanakapa.patch('locations/1/mail_address/1', { street: 'Updated Street' })

curl -X PATCH "https://ohana-api-demo.herokuapp.com/api/locations/1/mail_address/1" -d '{"address_1":"Updated Street"}' -H "X-Api-Token: test" -H "Content-Type: application/json"

When successful, the above command returns a 200 HTTP status code and JSON structured like this:

{
  "id": 1,
  "attention": null,
  "address_1": "Updated Street",
  "address_2": null,
  "city": "Redwood City",
  "state_province": "CA",
  "postal_code": "94065"
}

This endpoint updates an existing mail address for the specified location.

HTTP Request

PATCH https://ohana-api-demo.herokuapp.com/api/locations/:location_id/mail_address/:mail_address_id

JSON Parameters

Name	Type	Requirement	Detail
attention	string	optional	Any person the letter might be addressed to.
address_1	string	required	The primary part of the Street Address or P.O. Box number.
address_2	string	optional	The secondary part of the Street Address, such as the Suite, Room, or Floor number
city	string	required	The City name
state_province	string	required	2-letter US state_province abbreviation
postal_code	string	required	A valid postal code. Note that the API currently assumes this will be a US 5 or 9-digit ZIP code. 9-digit ZIP codes are separated with a dash, like this: 94025-9881. If you are using non-US data, you will need to replace the postal code validation with your own.
country	string	required	2-letter ISO 3361-1 country code

Delete an existing mail address

# Delete mail address with id 1 for location with id 1
Ohanakapa.delete('locations/1/mail_address/1')

curl --request DELETE "https://ohana-api-demo.herokuapp.com/api/locations/1/mail_address/1" -H "X-Api-Token: your_secret_token"

When successful, the above command returns a 204 HTTP status code with an empty body.

This endpoint deletes an existing mail address.

HTTP Request

DELETE https://ohana-api-demo.herokuapp.com/api/locations/:location_id/mail_address/:mail_address_id

Contacts

Get all contacts belonging to a location

# Provide an API Endpoint
Ohanakapa.configure do |c|
  c.api_endpoint = 'https://ohana-api-demo.herokuapp.com/api'
end

# Fetch all contacts belonging to the location with id 1
Ohanakapa.get('locations/1/contacts')

curl "https://ohana-api-demo.herokuapp.com/api/locations/1/contacts" -H "User-Agent: MyClient/1.0.0"

The above command returns JSON structured like this:

[
  {
    "department": null,
    "email": null,
    "id": 1,
    "name": "Susan Houston",
    "title": "Director of Older Adult Services",
    "phones": []
  },
  {
    "department": null,
    "email": null,
    "id": 2,
    "name": " Christina Gonzalez",
    "title": "Center Director",
    "phones": []
  }
]

This endpoint retrieves all contacts that belong to a particular location.

HTTP Request

GET https://ohana-api-demo.herokuapp.com/api/locations/:id/contacts

URL Parameters

Parameter	Default	Description
page	1	The particular page of results.
per_page	30	Amount of contacts to return per page, up to 100.

Create a new contact

# Create a contact for location with id 1
Ohanakapa.post('locations/1/contacts/', { department: 'Referrals', name: 'Moncef' })

curl -X POST "https://ohana-api-demo.herokuapp.com/api/locations/1/contacts" -d '{"department":"Referrals","name":"Moncef"}' -H "X-Api-Token: your_token" -H "Content-Type: application/json"

When successful, the above command returns a 201 HTTP status code and JSON structured like this:

{
  "id": 1,
  "email": null,
  "name": "Moncef",
  "title": null,
  "department": "Referrals",
  "phones": []
}

This endpoint creates a new contact for the specified entity.

HTTP Request

POST https://ohana-api-demo.herokuapp.com/api/locations/:location_id/contacts

JSON Parameters

Name	Type	Requirement	Detail
name	string	required	The Contact's full name
title	string	optional	The Contact's title
email	string	optional	The Contact's email address
department	string	optional	The department where the Contact works.

Update an existing contact

# Update contact with id 1 for location with id 1
Ohanakapa.patch('locations/1/contacts/1', { street: 'Updated Street' })

curl -X PATCH "https://ohana-api-demo.herokuapp.com/api/locations/1/contacts/1" -d '{"title":"Updated title"}' -H "X-Api-Token: test" -H "Content-Type: application/json"

When successful, the above command returns a 200 HTTP status code and JSON structured like this:

{
  "id": 1,
  "email": null,
  "name": "Moncef",
  "title": "Updated title",
  "department": "Referrals",
  "phones": []
}

This endpoint updates an existing contact for the specified location.

HTTP Request

PATCH https://ohana-api-demo.herokuapp.com/api/locations/:location_id/contacts/:contact_id

JSON Parameters

Name	Type	Requirement	Detail
name	string	required	The Contact's full name
title	string	optional	The Contact's title
email	string	optional	The Contact's email address
department	string	optional	The department where the Contact works.

Delete an existing contact

# Delete contact with id 1 for location 1
Ohanakapa.delete('/locations/1/contacts/1')

curl --request DELETE "https://ohana-api-demo.herokuapp.com/api/locations/1/contacts/1" -H "X-Api-Token: your_secret_token"

When successful, the above command returns a 204 HTTP status code with an empty body.

This endpoint deletes an existing contact for the specified entity.

HTTP Request

DELETE https://ohana-api-demo.herokuapp.com/api/locations/:location_id/contacts/:contact_id

Phones

Create a new phone

Phones can be created for either a location or a contact.

# Create a phone for location with id 1
Ohanakapa.post('locations/1/phones/', { number: '123-456-7890', extension: '1200', department: 'Referrals',  number_type: 'voice', country_prefix: '+1' })

curl -X POST "https://ohana-api-demo.herokuapp.com/api/locations/1/phones" -d '{"number": "123-456-7890", "extension": "1200", "department": "Referrals", "number_type": "voice", "country_prefix": "+1"}' -H "X-Api-Token: your_token" -H "Content-Type: application/json"

When successful, the above command returns a 201 HTTP status code and JSON structured like this:

{
  "id": 1,
  "number": "123-456-7890",
  "extension": "1200",
  "department": "Referrals",
  "number_type": "voice",
  "country_prefix": "+1"
}

This endpoint creates a new phone for the specified entity.

HTTP Request

For locations: POST https://ohana-api-demo.herokuapp.com/api/locations/:location_id/phones

For contacts: POST https://ohana-api-demo.herokuapp.com/api/locations/:location_id/contacts/:contact_id/phones

JSON Parameters

Name	Type	Requirement	Detail
number	string	required	The 10-digit US phone number.
vanity_number	string	optional	The 10-digit US phone number with vanity letters. For example: 703-555-HELP
extension	string	optional	The phone number extension. Must only contain numbers. For example: "1234"
department	string	optional	The department this phone number reaches.
number_type	string	required	Can be one of these four values: fax, voice, hotline, tty.
country_prefix	string	optional	The country prefix code, such as +1 for the USA.

Update an existing phone

Phones can be updated for either a location or a contact.

# Update phone with id 1 for location with id 1
Ohanakapa.patch('locations/1/phones/1', { number: '123-456-7890', extension: '1200', department: 'Referrals',  number_type: 'voice', country_prefix: '+1' })

curl -X PATCH "https://ohana-api-demo.herokuapp.com/api/locations/1/phones" -d '{"number": "123-456-7890", "extension": "1200", "department": "Referrals", "number_type": "voice", "country_prefix": "+1"}' -H "X-Api-Token: your_token" -H "Content-Type: application/json"

When successful, the above command returns a 201 HTTP status code and JSON structured like this:

{
  "id": 1,
  "number": "123-456-7890",
  "extension": "1200",
  "department": "Referrals",
  "number_type": "voice",
  "country_prefix": "+1"
}

This endpoint updates an existing phone for the specified entity.

HTTP Request

For locations: PATCH https://ohana-api-demo.herokuapp.com/api/locations/:location_id/phones/:phone_id

For contacts: PATCH https://ohana-api-demo.herokuapp.com/api/locations/:location_id/contacts/:contact_id/phones/:phone_id

JSON Parameters

Name	Type	Requirement	Detail
number	string	required	The 10-digit US phone number.
vanity_number	string	optional	The 10-digit US phone number with vanity letters. For example: 703-555-HELP
extension	string	optional	The phone number extension. Must only contain numbers. For example: "1234"
department	string	optional	The department this phone number reaches.
number_type	string	required	Can be one of these four values: fax, voice, hotline, tty.
country_prefix	string	optional	The country prefix code, such as +1 for the USA.

Delete an existing phone

# Delete phone with id 1 for location 1
Ohanakapa.delete('/locations/1/phones/1')

curl --request DELETE "https://ohana-api-demo.herokuapp.com/api/locations/1/phones/1" -H "X-Api-Token: your_secret_token"

When successful, the above command returns a 204 HTTP status code with an empty body.

This endpoint deletes an existing phone for the specified entity.

HTTP Request

For locations: DELETE https://ohana-api-demo.herokuapp.com/api/locations/:location_id/phones/:phone_id

For contacts: DELETE https://ohana-api-demo.herokuapp.com/api/locations/:location_id/contacts/:contact_id/phones/:phone_id

Services

Get all services belonging to a location

# Provide an API Endpoint
Ohanakapa.configure do |c|
  c.api_endpoint = 'https://ohana-api-demo.herokuapp.com/api'
end

# Fetch all services belonging to the location with id 1
Ohanakapa.get('locations/1/services')

curl "https://ohana-api-demo.herokuapp.com/api/locations/1/services" -H "User-Agent: MyClient/1.0.0"

The above command returns JSON structured like this:

[
  {
    "id": 22,
    "accepted_payments": [
      "Cash",
      "Credit Card",
      "Check"
    ],
    "alternate_name": "Fotos para pasaportes",
    "audience": "Profit and nonprofit businesses, the public, military facilities, schools and government entities",
    "description": "[NOTE THIS IS NOT A REAL SERVICE--THIS IS FOR TESTING PURPOSES OF THIS ALPHA APP] Lorem ipsum dolor sit amet, consectetur adipiscing elit. Praesent suscipit metus eu orci lobortis dictum. In hac habitasse platea dictumst. Vivamus vulputate, neque ut sodales gravida, lorem nunc pharetra ligula, ac cursus sem justo a sapien. Duis vitae vestibulum magna. Sed vel augue in justo rhoncus viverra. Nam ac felis a purus lobortis porttitor sit amet quis est. Suspendisse vulputate nisl quis nisi fermentum aliquet euismod at augue. Sed ultricies, purus dapibus tristique dictum, tortor mauris porttitor nulla, at porta nisl sem sed dolor. Proin ac hendrerit erat. Duis porta iaculis orci, eu euismod quam tristique in. Phasellus nec purus sit amet sapien volutpat egestas.",
    "eligibility": "None",
    "email": "passports@example.org",
    "fees": "None, except for permits and photocopying. Cash, checks and credit cards accepted",
    "funding_sources": [
      "City",
      "County",
      "Federal",
      "State"
    ],
    "application_process": "Walk in or apply by phone or mail",
    "keywords": [
      "Salud",
      "Medicina"
    ],
    "languages": [
      "English",
      "Spanish"
    ],
    "name": "Passport Photos",
    "required_documents": [
      "Government-issued identification"
    ],
    "service_areas": [
      "San Mateo County",
      "Alameda County"
    ],
    "status": "active",
    "website": "http://www.example.com",
    "wait_time": "No wait to 2 weeks",
    "updated_at": "2014-04-18T12:49:47.791-07:00",
    "categories": [],
    "contacts": [],
    "phones": [],
    "regular_schedules":[],
    "holiday_schedules":[]
  },
  {
    "id": 23,
    "audience": "Second service and nonprofit businesses, the public, military facilities, schools and government entities",
    "description": "[NOTE THIS IS NOT A REAL ORGANIZATION--THIS IS FOR TESTTING PURPOSES OF THIS ALPHA APP] Lorem ipsum dolor sit amet, consectetur adipiscing elit. Praesent suscipit metus eu orci lobortis dictum. In hac habitasse platea dictumst. Vivamus vulputate, neque ut sodales gravida, lorem nunc pharetra ligula, ac cursus sem justo a sapien. Duis vitae vestibulum magna. Sed vel augue in justo rhoncus viverra. Nam ac felis a purus lobortis porttitor sit amet quis est. Suspendisse vulputate nisl quis nisi fermentum aliquet euismod at augue. Sed ultricies, purus dapibus tristique dictum, tortor mauris porttitor nulla, at porta nisl sem sed dolor. Proin ac hendrerit erat. Duis porta iaculis orci, eu euismod quam tristique in. Phasellus nec purus sit amet sapien volutpat egestas.",
    "eligibility": "None",
    "fees": "None, except for permits and photocopying. Cash, checks and credit cards accepted",
    "funding_sources": [
      "City",
      "County",
      "Federal",
      "State"
    ],
    "application_process": "Walk in or apply by phone or mail",
    "keywords": [
      "Ruby on Rails/Postgres/Redis",
      "testing"
    ],
    "name": "Example Service Name",
    "service_areas": [
      "San Mateo County",
      "Alameda County"
    ],
    "status": "active",
    "website": "http://www.example.com",
    "wait_time": "No wait to 2 weeks",
    "categories": [],
    "contacts": [],
    "phones": [],
    "regular_schedules":[],
    "holiday_schedules":[]
  }
]

This endpoint retrieves all services that belong to a particular location.

HTTP Request

GET https://ohana-api-demo.herokuapp.com/api/locations/:id/services

Note that the URL above is just an example for the demo instance. To access an API that serves a particular region, you would need to look up the appropriate endpoint. All known API deployments are listed in the deployments section at the top of this page.

Query Parameters

Parameter	Default	Description
page	1	The particular page of results.
per_page	30	Amount of services to return per page, up to 100.

Create a new service

# Create a service for location with id 1
Ohanakapa.post('locations/1/services', { name: 'Free Eye Exam', audience: 'Low-income children between the ages of 5 and 12.', description: 'Provides free eye exams for low-income children between the ages of 5 and 12.' })

curl -X POST "https://ohana-api-demo.herokuapp.com/api/locations/1/services" -d '{"audience":"Low-income children","description":"Provides free eye exams for low-income children between the ages of 5 and 12","name":"Free Eye Exam"}' -H "X-Api-Token: your_token" -H "Content-Type: application/json"

When successful, the above command returns a 201 HTTP status code and JSON structured like this:

{
  "id": 22,
  "accepted_payments": [
    "Cash",
    "Credit Card",
    "Check"
  ],
  "alternate_name": "Fotos para pasaportes",
  "audience": "Profit and nonprofit businesses, the public, military facilities, schools and government entities",
  "description": "[NOTE THIS IS NOT A REAL SERVICE--THIS IS FOR TESTING PURPOSES OF THIS ALPHA APP] Lorem ipsum dolor sit amet, consectetur adipiscing elit. Praesent suscipit metus eu orci lobortis dictum. In hac habitasse platea dictumst. Vivamus vulputate, neque ut sodales gravida, lorem nunc pharetra ligula, ac cursus sem justo a sapien. Duis vitae vestibulum magna. Sed vel augue in justo rhoncus viverra. Nam ac felis a purus lobortis porttitor sit amet quis est. Suspendisse vulputate nisl quis nisi fermentum aliquet euismod at augue. Sed ultricies, purus dapibus tristique dictum, tortor mauris porttitor nulla, at porta nisl sem sed dolor. Proin ac hendrerit erat. Duis porta iaculis orci, eu euismod quam tristique in. Phasellus nec purus sit amet sapien volutpat egestas.",
  "eligibility": "None",
  "email": "passports@example.org",
  "fees": "None, except for permits and photocopying. Cash, checks and credit cards accepted",
  "funding_sources": [
    "City",
    "County",
    "Federal",
    "State"
  ],
  "application_process": "Walk in or apply by phone or mail",
  "keywords": [
    "Salud",
    "Medicina"
  ],
  "languages": [
    "English",
    "Spanish"
  ],
  "name": "Passport Photos",
  "required_documents": [
    "Government-issued identification"
  ],
  "service_areas": [
    "San Mateo County",
    "Alameda County"
  ],
  "status": "active",
  "website": "http://www.example.com",
  "wait_time": "No wait to 2 weeks",
  "updated_at": "2014-04-18T12:49:47.791-07:00",
  "categories": [],
  "regular_schedules":[],
  "holiday_schedules":[]
}

This endpoint creates a new service for a location.

HTTP Request

POST https://ohana-api-demo.herokuapp.com/api/locations/:location_id/services

JSON Parameters

Name	Type	Requirement	Detail
accepted_payments	Array of Strings	optional	Methods of payment for this service, such as ['Cash', 'Credit Card', 'Medicare']. You can define the list of all possible payment methods in settings.yml.
alternate_name	string	optional	Another name this Service might be known by.
application_process	string	optional	Description of the service's application process
audience	string	optional	Group of people served
categories	array of objects	optional	Categories assigned to the service based on the Open Eligibility taxonomy. See the Categories section for more details.
description	string	required	Description of the service provided
eligibility	string	optional	Requirements to receive the service
email	string	optional	The service's main email address.
fees	string	optional	Fees charged to receive the service
funding_sources	array of strings	optional	Source of funds used to support the service
keywords	array of strings	optional	Keywords that people might use to search for this service, but that you might not want to include in the service description (such as common misspellings).
languages	array of strings	optional	Languages in which this service is provided. You can define the list of all possible languages in settings.yml.
name	string	required	Name of the service
required_documents	array of strings	optional	The documents that are required to receive this service. You can define the list of all possible documents in settings.yml.
service_areas	array of strings	optional	Cities, Counties, or other geographical area served. The values will typically be validated against a list of service areas defined in a deployment's settings.yml.
status	string	required	Must be one of active, defunct, or inactive.
wait_time	string	optional	Wait times associated with the service
website	string	optional	The service's website. Must include "http://" or "https://"

Update an existing service

# Update service with id 22 for location with id 22
Ohanakapa.patch('locations/22/services/22', { name: 'Updated Service' })

curl -X PATCH "https://ohana-api-demo.herokuapp.com/api/locations/22/services/22" -d '{"name":"Updated Service"}' -H "X-Api-Token: test" -H "Content-Type: application/json"

When successful, the above command returns a 200 HTTP status code and JSON structured like this:

{
  "id": 1,
  "accepted_payments": [
    "Cash",
    "Credit Card",
    "Check"
  ],
  "alternate_name": "Fotos para pasaportes",
  "audience": "Profit and nonprofit businesses, the public, military facilities, schools and government entities",
  "description": "[NOTE THIS IS NOT A REAL SERVICE--THIS IS FOR TESTING PURPOSES OF THIS ALPHA APP] Lorem ipsum dolor sit amet, consectetur adipiscing elit. Praesent suscipit metus eu orci lobortis dictum. In hac habitasse platea dictumst. Vivamus vulputate, neque ut sodales gravida, lorem nunc pharetra ligula, ac cursus sem justo a sapien. Duis vitae vestibulum magna. Sed vel augue in justo rhoncus viverra. Nam ac felis a purus lobortis porttitor sit amet quis est. Suspendisse vulputate nisl quis nisi fermentum aliquet euismod at augue. Sed ultricies, purus dapibus tristique dictum, tortor mauris porttitor nulla, at porta nisl sem sed dolor. Proin ac hendrerit erat. Duis porta iaculis orci, eu euismod quam tristique in. Phasellus nec purus sit amet sapien volutpat egestas.",
  "eligibility": "None",
  "email": "passports@example.org",
  "fees": "None, except for permits and photocopying. Cash, checks and credit cards accepted",
  "funding_sources": [
    "City",
    "County",
    "Federal",
    "State"
  ],
  "application_process": "Walk in or apply by phone or mail",
  "keywords": [
    "Salud",
    "Medicina"
  ],
  "languages": [
    "English",
    "Spanish"
  ],
  "name": "Updated Service",
  "required_documents": [
    "Government-issued identification"
  ],
  "service_areas": [
    "San Mateo County",
    "Alameda County"
  ],
  "status": "active",
  "website": "http://www.example.com",
  "wait_time": "No wait to 2 weeks",
  "updated_at": "2014-04-18T12:49:47.791-07:00",
  "categories": [],
  "contacts": [],
  "phones": [],
  "regular_schedules":[],
  "holiday_schedules":[]
}

This endpoint updates an existing service for the specified location.

HTTP Request

PATCH https://ohana-api-demo.herokuapp.com/api/locations/:location_id/services/:service_id

JSON Parameters

Name	Type	Requirement	Detail
accepted_payments	Array of Strings	optional	Methods of payment for this service, such as ['Cash', 'Credit Card', 'Medicare']. You can define the list of all possible payment methods in settings.yml.
alternate_name	string	optional	Another name this Service might be known by.
application_process	string	optional	Description of the service's application process
audience	string	optional	Group of people served
categories	array of objects	optional	Categories assigned to the service based on the Open Eligibility taxonomy. See the Categories section for more details.
description	string	required	Description of the service provided
eligibility	string	optional	Requirements to receive the service
email	string	optional	The service's main email address.
fees	string	optional	Fees charged to receive the service
funding_sources	array of strings	optional	Source of funds used to support the service
keywords	array of strings	optional	Keywords that people might use to search for this service, but that you might not want to include in the service description (such as common misspellings).
languages	array of strings	optional	Languages in which this service is provided. You can define the list of all possible languages in settings.yml.
name	string	required	Name of the service
required_documents	array of strings	optional	The documents that are required to receive this service. You can define the list of all possible documents in settings.yml.
service_areas	array of strings	optional	Cities, Counties, or other geographical area served. The values will typically be validated against a list of service areas defined in a deployment's settings.yml.
status	string	required	Must be one of active, defunct, or inactive.
wait_time	string	optional	Wait times associated with the service
website	string	optional	The service's website. Must include "http://" or "https://"

Delete an existing service

# Delete service with id 1 for location with id 1
Ohanakapa.delete('locations/1/service/1')

curl --request DELETE "https://ohana-api-demo.herokuapp.com/api/locations/1/service/1" -H "X-Api-Token: your_secret_token"

When successful, the above command returns a 204 HTTP status code with an empty body.

This endpoint deletes an existing service.

HTTP Request

DELETE https://ohana-api-demo.herokuapp.com/api/locations/:location_id/service/:service_id

Search Locations

Get locations that match certain criteria.

# Provide an API Endpoint
Ohanakapa.configure do |c|
  c.api_endpoint = 'https://ohana-api-demo.herokuapp.com/api'
end

# Fetch all locations within 2 miles of ZIP code 94103
Ohanakapa.search('search', { location: '94103', radius: 2 })

curl "https://ohana-api-demo.herokuapp.com/api/search?location=94103&radius=2" -H "User-Agent: MyClient/1.0.0"

The above command returns JSON structured like this:

[
  {
    "id": 22,
    "active": true,
    "admin_emails": [ ],
    "coordinates": [
      -122.4456187,
      37.7517064
    ],
    "description": "Testing adding a new location",
    "latitude": 37.7517064,
    "longitude": -122.4456187,
    "name": "New location test",
    "short_desc": null,
    "slug": "new-location-test",
    "website": null,
    "updated_at": "2014-09-10T08:21:14.853-07:00",
    "contacts_url": "https://ohana-api-demo.herokuapp.com/api/locations/new-location-test/contacts",
    "services_url": "https://ohana-api-demo.herokuapp.com/api/locations/new-location-test/services",
    "url": "https://ohana-api-demo.herokuapp.com/api/locations/new-location-test",
    "address": {
      "id": 28,
      "address_1": "1290 Ridder Park Drive",
      "address_2": null,
      "city": "San Francisco",
      "state_province": "CA",
      "postal_code": "94103"
    },
    "organization": {
      "id": 8,
      "accreditations": [],
      "alternate_name": null,
      "date_incorporated": null,
      "description": "Test description",
      "email": null,
      "funding_sources": [],
      "licenses": [],
      "name": "Admin Test Org",
      "slug": "admin-test-org",
      "website": null,
      "url": "https://ohana-api-demo.herokuapp.com/api/organizations/admin-test-org",
      "locations_url": "https://ohana-api-demo.herokuapp.com/api/organizations/admin-test-org/locations"
    },
    "phones": [
      {
        "id":43,
        "department":"Information",
        "extension":"123",
        "number":"650 372-6200",
        "number_type":"voice",
        "vanity_number":"222-555-INFO"
      },
      {
        "id":44,
        "department":"Reservations",
        "extension":null,
        "number":"650 627-8244",
        "number_type":"fax",
        "vanity_number":null
      }
    ]
  },
  {
    "id": 15,
    "active": true,
    "admin_emails": [ ],
    "coordinates": [
      -122.4136494,
      37.7756408
    ],
    "description": "Location with no service",
    "latitude": 37.7756408,
    "longitude": -122.4136494,
    "name": "Location with no service",
    "short_desc": null,
    "slug": "location-with-no-service",
    "website": null,
    "updated_at": "2014-09-10T08:21:14.848-07:00",
    "contacts_url": "https://ohana-api-demo.herokuapp.com/api/locations/location-with-no-service/contacts",
    "services_url": "https://ohana-api-demo.herokuapp.com/api/locations/location-with-no-service/services",
    "url": "https://ohana-api-demo.herokuapp.com/api/locations/location-with-no-service",
    "address": {
      "id": 27,
      "address_1": "155 9th St",
      "address_2": null,
      "city": "San Francisco",
      "state_province": "CA",
      "postal_code": "94103"
    },
    "organization": {
      "id": 8,
      "accreditations": [],
      "alternate_name": null,
      "date_incorporated": null,
      "description": "Test description",
      "email": null,
      "funding_sources": [],
      "licenses": [],
      "name": "Admin Test Org",
      "slug": "admin-test-org",
      "website": null,
      "url": "https://ohana-api-demo.herokuapp.com/api/organizations/admin-test-org",
      "locations_url": "https://ohana-api-demo.herokuapp.com/api/organizations/admin-test-org/locations"
    },
    "phones": [ ]
  }
]

This endpoint retrieves all locations that match the criteria based on the parameters below. Multiple parameters can be used at the same time, separated by an ampersand (&).

HTTP Request

GET https://ohana-api-demo.herokuapp.com/api/search{?category,email,keyword,language,lat_lng,location,org_name,radius,service_area,status}

Sorting of results

Except for location-based and keyword-based searches, results are sorted by location id in ascending order. Location-based searches (those that use the lat_lng or location parameter) are sorted by distance, with the ones closest to the search query appearing first. keyword searches are sorted by relevance since they perform a full-text search in various fields across various tables. See the keyword parameter description below for more details.

URL Query Parameters

Parameter	Description
category	The name of the Service category. By default, Ohana API uses the Open Eligibility taxonomy for Human Services. The parameter must be spelled exactly as in the Open Eligibility taxonomy, including capitalizations and spaces. Some deployments might choose to use their own taxonomy. In that case, refer to their documentation. You can either pass in one category as a String or multiple categories as an Array. For example: https://ohana-api-demo.herokuapp.com/api/search?category[]=Transit&category[]=Care. This will return Locations with Services that are associated with either the Transit or Care categories.
email	This is only useful if you're building an external admin interface. It allows you to determine which locations the user that just signed in has access to. When you pass in an email to the API, it first checks to see if the domain name portion of the email matches one of the generic domains defined in settings.yml. If it does, then it finds locations whose admin_emails matches the user's email or whose email matches the email. Otherwise, if it doesn't match a generic domain, then it will find locations whose admin_emails matches the email, or whose website matches the domain name, or whose email matches the domain name. Read the source code for more details.
keyword	You can pass in one or more words, and the API will look for the occurrence of those words in the following fields: the organization's name, the location's name, the location's description, the service's name, the service's description, the service's keywords, and the service's categories. If more than one word is passed, the API will return matches where all of the words are present (but not necessarily as a phrase). Matches within the location's description, the service's description, and the service's category names are ranked higher than matches in the other fields. This full text search is performed via a Postgres tsvector column and the pg_search gem.
language	Returns locations whose languages field matches the parameter. You can either pass in one language as a String or multiple languages as an Array. For example: https://ohana-api-demo.herokuapp.com/api/search?language[]=Spanish&language[]=French. This will return locations whose languages field contains either Spanish or French.
lat_lng	Find locations near a specific latitude and longitude. This parameter must be a comma-delimited lat,long pair of floats. For example: https://ohana-api-demo.herokuapp.com/api/search?lat_lng=37.477227,-122.213221. By default, this will find locations within a 5-mile radius of those coordinates. To use a different radius, pass in the radius parameter (see description below).
location	Find locations near a specific address or ZIP code. For example: https://ohana-api-demo.herokuapp.com/api/search?location=94403. By default, this will find locations within a 5-mile radius of those coordinates. To use a different radius, pass in the radius parameter (see description below).
org_name	Find locations that belong to an Organization whose name matches the parameter. If more than one word is passed, the API will return matches where all of the words are present (but not necessarily as a phrase).
radius	Use this parameter in conjunction with the location or lat_lng parameter to define the search area in miles. The default value is 5, the minimum value is 0.1, and the maximum value is 50.
service_area	Find locations whose services are available in a particular service area. For example: https://ohana-api-demo.herokuapp.com/api/search?service_area=belmont. The list of valid service areas will usually be defined in a deployment's settings.yml.
status	If set to active, it finds Locations that have at least one active Service. If set to inactive, it finds Locations that don't have any active Services.
page	The particular page of results. Default is 1.
per_page	Amount of locations to return per page, up to 100. Default is 30.

Nearby

Find locations that are near a specific location.

# Provide an API Endpoint
Ohanakapa.configure do |c|
  c.api_endpoint = 'https://ohana-api-demo.herokuapp.com/api'
end

# Fetch all locations within 2 miles of ZIP code 94103
Ohanakapa.get('locations/22/nearby', radius: 2)

curl "https://ohana-api-demo.herokuapp.com/api/locations/22/nearby?radius=2" -H "User-Agent: MyClient/1.0.0"

The above command returns a summarized JSON representation containing the following location attributes:

[
  {
    "id": 15,
    "alternate_name": null,
    "latitude": 37.7517064,
    "longitude": -122.4456187,
    "name": "New location test",
    "slug": "new-location-test",
    "address": {
      "id": 28,
      "address_1": "1290 Ridder Park Drive",
      "address_2": null,
      "city": "San Francisco",
      "state_province": "CA",
      "postal_code": "94103"
    }
  }
]

This endpoint retrieves all locations that are near the specified location.

HTTP Request

GET https://ohana-api-demo.herokuapp.com/api/locations/:location_id/nearby

URL Query Parameters

Parameter	Description
radius	Default in miles is 0.5, minimum is 0.1, and maximum is 50.
page	The particular page of results. Default is 1.
per_page	Amount of locations to return per page, up to 100. Default is 30.

Categories

Get all categories

# Provide an API Endpoint
Ohanakapa.configure do |c|
  c.api_endpoint = 'https://ohana-api-demo.herokuapp.com/api'
end

# Fetch all locations
Ohanakapa.categories

curl "https://ohana-api-demo.herokuapp.com/api/categories" -H "User-Agent: MyClient/1.0.0"

The above command returns JSON structured like this:

[
  {
    "id": 1,
    "depth": 0,
    "taxonomy_id": "101",
    "name": "Emergency",
    "parent_id": null
  },
  {
    "id": 2,
    "depth": 1,
    "taxonomy_id": "101-01",
    "name": "Disaster Response",
    "parent_id": 1
  },
  {
    "id": 3,
    "depth": 1,
    "taxonomy_id": "101-02",
    "name": "Emergency Cash",
    "parent_id": 1
  },
  {
    "id": 4,
    "depth": 2,
    "taxonomy_id": "101-02-01",
    "name": "Help Pay for Food",
    "parent_id": 3
  }
]

This endpoint retrieves all categories.

HTTP Request

GET https://ohana-api-demo.herokuapp.com/api/categories

The categories are based on the taxonomy used by the instance of the API. By default, the API uses the Open Eligibility Human Services taxonomy. Categories are organized in a tree structure using the Ancestry gem.

Get a category's children categories

# Provide an API Endpoint
Ohanakapa.configure do |c|
  c.api_endpoint = 'https://ohana-api-demo.herokuapp.com/api'
end

# Fetch all children of the category with a specific `taxonomy_id`.
Ohanakapa.get('categories/:category_taxonomy_id/children')

# Fetch all children of the category with a specific `taxonomy_id`.

curl "https://ohana-api-demo.herokuapp.com/api/categories/101/children" -H "User-Agent: MyClient/1.0.0"

The above command returns JSON structured like this:

[
  {
    "id":2,
    "depth":1,
    "taxonomy_id":"101-01",
    "name":"Disaster Response",
    "parent_id":1
  },
  {
    "id":3,
    "depth":1,
    "taxonomy_id":"101-02",
    "name":"Emergency Cash",
    "parent_id":1
  },
  {
    "id":10,
    "depth":1,
    "taxonomy_id":"101-03",
    "name":"Emergency Food",
    "parent_id":1
  },
  {
   "id":11,
   "depth":1,
   "taxonomy_id":"101-04",
   "name":"Emergency Shelter",
   "parent_id":1
  },
  {
    "id":12,
    "depth":1,
    "taxonomy_id":"101-05",
    "name":"Help Find Missing Persons",
    "parent_id":1
  },
  {
    "id":13,
    "depth":1,
    "taxonomy_id":"101-06",
    "name":"Immediate Safety",
    "parent_id":1
  },
  {
    "id":16,
    "depth":1,
    "taxonomy_id":"101-07",
    "name":"Psychiatric Emergency Services",
    "parent_id":1
  }
]

This endpoint retrieves all children categories of a specific category.

HTTP Request

GET https://ohana-api-demo.herokuapp.com/api/categories/:category_taxonomy_id/children

Update a service's categories

# Update categories for the service with id 1 by passing in an array of
# taxonomy_ids.
Ohanakapa.put('services/1/categories', { taxonomy_ids: ['101', '102'] })

# Update categories for the service with id 1 by passing in an array of
# taxonomy_ids.

curl -X PUT "https://ohana-api-demo.herokuapp.com/api/services/1/categories" -d '{"taxonomy_ids": ["101", "102"]}' -H "X-Api-Token: your_token" -H "Content-Type: application/json"

When successful, the above command returns the updated service with a 200 HTTP status code:

{
  "id":1,
  "accepted_payments":[],
  "alternate_name":null,
  "audience":"Older adults age 55 or over, ethnic minorities and low-income persons",
  "description":"A walk-in center for older adults that provides social services, wellness, recreational, educational and creative activities including arts and crafts, computer classes and gardening classes.",
  "eligibility":"Age 55 or over for most programs, age 60 or over for lunch program",
  "email":null,
  "fees":"$2.50 suggested donation for lunch for age 60 or over, donations for other services appreciated. Cash and checks accepted.",
  "funding_sources":["City","County","Donations","Fees","Fundraising"],
  "application_process":"Walk in or apply by phone.",
  "keywords":[],
  "languages":[],
  "name":"Fair Oaks Adult Activity Center",
  "required_documents":[],
  "service_areas":["Colma"],
  "status":"active",
  "website":null,
  "wait_time":"No wait.",
  "updated_at":"2014-10-21T16:02:55.656-07:00",
  "categories":[
    {
      "id": 1,
      "depth": 0,
      "taxonomy_id": "101",
      "name": "Emergency",
      "parent_id": null
    },
    {
      "id": 17,
      "depth": 0,
      "taxonomy_id": "102",
      "name": "Food",
      "parent_id": null
    }
  ]
}

This endpoint updates a service with the specified categories.

HTTP Request

PUT https://ohana-api-demo.herokuapp.com/api/services/:service_id/categories

JSON Parameters

Name	Type	Requirement	Detail
taxonomy_ids	Array	required	An array of valid taxonomy_ids.

Pagination

Requests that return multiple items will be paginated to 30 items by default. You can specify further pages with the ?page parameter. For some resources, you can also set a custom page size up to 100 with the ?per_page parameter.

Note that page numbering is 1-based and that omitting the ?page parameter will return the first page.

curl 'http://api.smc-connect.org/locations?page=2&per_page=10'

Ohanakapa.locations(page: 2, per_page: 10)

Link Header

The pagination info is included in the Link header. It is important to follow these Link header values instead of constructing your own URLs.

A Link Header appears in the HTTP Response like this:

Link: <http://api.smc-connect.org/locations?page=57>; rel="last", <http://api.smc-connect.org/locations?page=2>; rel="next"

The possible rel values are:

Name	Description
next	Shows the URL of the immediate next page of results.
last	Shows the URL of the last page of results.
first	Shows the URL of the first page of results.
prev	Shows the URL of the immediate previous page of results.

Errors

The Ohana API uses the following error codes:

Error Code	Meaning
400	Bad Request -- You passed an invalid URL parameter
401	Unauthorized -- You sent a missing or invalid X-Api-Token value
404	Not Found -- The specified entity could not be found
406	Not Acceptable -- You requested a format that isn't JSON
422	Unprocessable Entity -- You sent an invalid entity attribute
500	Internal Server Error -- The app generated an error. Please try again later.
503	Service Unavailable -- We're temporarily offline. Please try again later.