GoodMap API Documentation


Introduction

GoodMap provides a REST API to users. The API can be used to fetch data, integrate with other products, or build custom applications on top of GoodMap.

All URL paths are relative to the main domain: https://app.getgoodmap.com/api/v1

Have a suggestion for a correction or improvement to our API docs? Please email paul@goodmapstl.org


Authentication

Accessing the GoodMap API requires a secret API token and user email. API tokens can be found in your user profile.

Each API request must have the following headers:

Name Type Value
X-User-Token String Required. The API key of your user.
Content-Type String Required. "application/json"
X-User-Email String Required. The email address of your user.

Organizations

The Organization API allows you to create and update organizations.

Field Type
id integer (auto-generated)
name string
slug string (auto-generated)
description text
street_address string
street_address_2 string
state string
city string
zip string
county string
country string
phone string
email string
website string
other_categories string
contact_name string
contact_title string
contact_email string
contact_phone string
year_incorporate integer
tax_status string
accrediation string
licenses string
transportation_details text
tax_form_990_link string
annual_report_link string
united_way_211_link string
latitude float (auto-generated)
longitude float (auto-generated)
tag_list string
imported boolean
active boolean
avatar string
user_id integer

Examples

GET /organizations

Results

                  
    [
        {
            "id": 34,
            "name": "Nine Network of Public Media",
            "slug": "nine-network-of-public-media",
            "description": "To ignite the spirit of possibility through public media.",
            "street_address": null,
            "street_address_2": null,
            "state": null,
            "city": null,
            "zip": null,
            "county": null,
            "country": null,
            "phone": "314-512-9659",
            "email": "lforsythe@ketc.org",
            "website": null,
            "other_categories": null,
            "contact_name": null,
            "contact_title": null,
            "contact_email": null,
            "contact_phone": null,
            "year_incorporated": null,
            "tax_status": null,
            "accreditation": null,
            "licenses": null,
            "transportation_details": null,
            "tax_form_990_link": null,
            "annual_report_link": null,
            "united_way_211_link": null,
            "tag_list": [],
            "latitude": null,
            "longitude": null,
            "imported": true,
            "active": true,
            "avatar": {
                "url": null
            },
            "files": [],
            "guides_count": null,
            "services_count": 0,
            "accounts_count": 0,
            "user_id": 43,
            "created_at": "2017-09-25T22:29:36.944Z",
            "updated_at": "2017-09-25T22:29:36.944Z"
        },
        {
            "id": 38,
            "name": "Preferred Family Healthcare",
            ...
        }
      ]
                  
                

GET /organizations/54

Results

Requesting a single organization will also return basic information about services and categories.

                  
      {
          "id": 54,
          "name": "Natural Bridge Branch, St. Louis County Library",
          "slug": "natural-bridge-branch-st-louis-county-library",
          "description": "The mission of the St. Louis County Library District is to provide the resources and services to enrich individual minds, enhance lives and expand perspectives.",
          "street_address": "7606 Natural Bridge Rd.",
          "street_address_2": null,
          "state": "MO",
          "city": "St. Louis",
          "zip": "63121",
          "county": null,
          "country": null,
          "phone": "314-994-3300",
          "email": "naturalbridge@slcl.org",
          "website": "http://www.slcl.org",
          "other_categories": null,
          "contact_name": null,
          "contact_title": null,
          "contact_email": null,
          "contact_phone": null,
          "year_incorporated": null,
          "tax_status": null,
          "accreditation": null,
          "licenses": null,
          "transportation_details": null,
          "tax_form_990_link": null,
          "annual_report_link": null,
          "united_way_211_link": null,
          "tag_list": [],
          "latitude": 38.7055596,
          "longitude": -90.3009355,
          "imported": true,
          "active": true,
          "avatar": {
              "url": null
          },
          "files": [],
          "guides_count": null,
          "services_count": 2,
          "accounts_count": 0,
          "user_id": 11,
          "created_at": "2017-09-25T22:29:57.186Z",
          "updated_at": "2017-09-25T22:29:57.186Z",
          "services": [
              {
                  "id": 2,
                  "name": "Library Services"
              },
              {
                  "id": 1,
                  "name": "The Gift of Reading Program"
              }
          ],
          "categories": [
              {
                  "id": 19,
                  "name": "Education"
              }
          ]
      }
                  
                

POST /organizations

JSON body

                  
      {
              "name": "Test Org API 1",
              "description": "Test Description",
              "category_ids": ["1", "2"],
              "street_address": null,
              "street_address_2": null,
              "state": null,
              "city": null,
              "zip": null,
              "county": null,
              "country": null,
              "phone": "314-512-1234",
              "email": "test@email.org",
              "website": null,
              "other_categories": null,
              "contact_name": null,
              "contact_title": null,
              "contact_email": null,
              "contact_phone": null,
              "year_incorporated": null,
              "tax_status": null,
              "accreditation": null,
              "licenses": null,
              "transportation_details": null,
              "tax_form_990_link": null,
              "annual_report_link": null,
              "united_way_211_link": null
      }
                  
                

Results

                  
      {
          "id": 60,
          "name": "Test Org API 1",
          "slug": "test-org-api-1-1",
          "description": "Test Description",
          "street_address": null,
          "street_address_2": null,
          "state": null,
          "city": null,
          "zip": null,
          "county": null,
          "country": null,
          "phone": "314-512-1234",
          "email": "test@email.org",
          "website": null,
          "other_categories": null,
          "contact_name": null,
          "contact_title": null,
          "contact_email": null,
          "contact_phone": null,
          "year_incorporated": null,
          "tax_status": null,
          "accreditation": null,
          "licenses": null,
          "transportation_details": null,
          "tax_form_990_link": null,
          "annual_report_link": null,
          "united_way_211_link": null,
          "tag_list": [],
          "latitude": null,
          "longitude": null,
          "imported": false,
          "active": true,
          "avatar": {
              "url": null
          },
          "files": [],
          "guides_count": null,
          "services_count": 0,
          "accounts_count": 0,
          "user_id": 1,
          "created_at": "2019-05-25T20:25:33.125Z",
          "updated_at": "2019-05-25T20:25:33.125Z"
      }
                  
                

PATCH /organizations/60

JSON body

                  
      {
              "name": "Test Org API 1 updated"
      }
                  
                

Results

                  
      {
          "id": 60,
          "name": "Test Org API 1 updated",
          "slug": "test-org-api-1-1",
          "description": "Test Description",
          "category_ids": ["1", "2"],
          "street_address": null,
          "street_address_2": null,
          "state": null,
          "city": null,
          "zip": null,
          "county": null,
          "country": null,
          "phone": "314-512-1234",
          "email": "test@email.org",
          "website": null,
          "other_categories": null,
          "contact_name": null,
          "contact_title": null,
          "contact_email": null,
          "contact_phone": null,
          "year_incorporated": null,
          "tax_status": null,
          "accreditation": null,
          "licenses": null,
          "transportation_details": null,
          "tax_form_990_link": null,
          "annual_report_link": null,
          "united_way_211_link": null,
          "tag_list": [],
          "latitude": null,
          "longitude": null,
          "imported": false,
          "active": true,
          "avatar": {
              "url": null
          },
          "files": [],
          "guides_count": null,
          "services_count": 0,
          "accounts_count": 0,
          "user_id": 1,
          "created_at": "2019-05-25T20:25:33.125Z",
          "updated_at": "2019-05-25T20:25:33.125Z"
      }
                  
                

Services

The Service API allows you to create and update services.

Field Type
id integer
name string
slug string (auto-generated)
description text
how_to_access text
eligibility text
area_served text
schedule text
required_documents text
application_process text
fees text
language_services text
accessibility text
cost integer
street_address string
street_address_2 string
state string
city string
zip string
county string
country string
phone string
email string
website string
other_categories string
contact_name string
contact_title string
transportation_details text
united_way_211_link string
latitude float (auto-generated)
longitude float (auto-generated)
imported boolean
active boolean
user_id integer
organization_id integer
tag_list string

Examples

GET /organization/:id/services

Results

                  
    [
        {
            "id": 2,
            "name": "Test Service 2",
            "slug": "test-service-2",
            "description": "Service description.",
            "how_to_access": "",
            "eligibility": "",
            "area_served": null,
            "schedule": "",
            "required_documents": "",
            "application_process": "",
            "fees": "",
            "language_services": "",
            "accessibility": "",
            "transportation_details": "",
            "united_way_211_link": "",
            "other_categories": "",
            "contact_name": "",
            "contact_title": "",
            "cost": null,
            "tag_list": [],
            "street_address": "",
            "street_address_2": "",
            "state": "",
            "city": "",
            "zip": "",
            "county": "",
            "country": null,
            "phone": "",
            "email": "",
            "website": "",
            "latitude": null,
            "longitude": null,
            "files": [],
            "guides_count": null,
            "imported": false,
            "active": true,
            "organization_id": 1,
            "user_id": null,
            "created_at": "2019-06-01T20:55:30.386Z",
            "updated_at": "2019-06-01T20:55:30.444Z"
        },
        {
            "id": 1,
            "name": "Test Service",
            ...
        }
    ]
                  
                

GET /organizations/1/services/1

Results

Requesting a single service will return basic information about the service.

                  
                    {
                        "id": 1,
                        "name": "Test Service",
                        "slug": "test-service",
                        "description": "Service description.",
                        "how_to_access": "",
                        "eligibility": "",
                        "area_served": null,
                        "schedule": "",
                        "required_documents": "",
                        "application_process": "",
                        "fees": "",
                        "language_services": "",
                        "accessibility": "",
                        "transportation_details": "",
                        "united_way_211_link": "",
                        "other_categories": "",
                        "contact_name": "",
                        "contact_title": "",
                        "cost": null,
                        "tag_list": [],
                        "street_address": "",
                        "street_address_2": "",
                        "state": "",
                        "city": "",
                        "zip": "",
                        "county": "",
                        "country": null,
                        "phone": "",
                        "email": "",
                        "website": "",
                        "latitude": null,
                        "longitude": null,
                        "files": [],
                        "guides_count": null,
                        "imported": false,
                        "active": true,
                        "organization_id": 1,
                        "user_id": null,
                        "created_at": "2019-06-01T20:49:55.741Z",
                        "updated_at": "2019-06-01T20:49:55.889Z"
                    }
                  
                

POST /organizations/1/services

JSON body

                  
      {
              "name": "Test Service 6",
              "description": "Service Description",
      }
                  
                

Results

                  
    {
        "id": 5,
        "name": "Test Service 6",
        "slug": "test-service-6",
        "description": "Service Description",
        "category_ids": ["1", "2"],
        "how_to_access": null,
        "eligibility": null,
        "area_served": null,
        "schedule": null,
        "required_documents": null,
        "application_process": null,
        "fees": null,
        "language_services": null,
        "accessibility": null,
        "transportation_details": null,
        "united_way_211_link": null,
        "other_categories": null,
        "contact_name": null,
        "contact_title": null,
        "cost": null,
        "tag_list": [],
        "street_address": "",
        "street_address_2": "",
        "state": "",
        "city": "",
        "zip": "",
        "county": "",
        "country": null,
        "phone": "",
        "email": "",
        "website": "",
        "latitude": null,
        "longitude": null,
        "files": [],
        "guides_count": null,
        "imported": false,
        "active": true,
        "organization_id": 1,
        "user_id": null,
        "created_at": "2019-06-01T21:13:00.295Z",
        "updated_at": "2019-06-01T21:13:00.336Z"
    }
                  
                

PATCH /organizations/1/services/5

JSON body

                  
                {
                        "description": "Service Description updated."
                }
                  
                

Results

                  
                    {
                        "organization_id": 1,
                        "id": 5,
                        "description": "Service Description updated.",
                        "category_ids": ["1", "2"],
                        "files": [],
                        "name": "Test Service 6",
                        "slug": "test-service-6",
                        "cost": null,
                        "street_address": "",
                        "city": "",
                        "state": "",
                        "zip": "",
                        "how_to_access": null,
                        "eligibility": null,
                        "area_served": null,
                        "schedule": null,
                        "required_documents": null,
                        "application_process": null,
                        "fees": null,
                        "language_services": null,
                        "accessibility": null,
                        "transportation_details": null,
                        "united_way_211_link": null,
                        "other_categories": null,
                        "contact_name": null,
                        "contact_title": null,
                        "tag_list": [],
                        "street_address_2": "",
                        "county": "",
                        "country": null,
                        "phone": "",
                        "email": "",
                        "website": "",
                        "latitude": null,
                        "longitude": null,
                        "guides_count": null,
                        "imported": false,
                        "active": true,
                        "user_id": null,
                        "created_at": "2019-06-01T21:13:00.295Z",
                        "updated_at": "2019-06-01T21:18:36.972Z"
                    }
                  
                

Categories

The Category API allows you to view all categories.

Field Type
id integer
name string
slug string (auto-generated)
organizations_count integer
services_count integer
select_order integer
imported boolean
is_core boolean
show_on_homepage boolean
account_id integer
parent_id integer
lft integer
rgt integer
depth integer
children_count integer

Examples

GET /categories

Results

                  
                    [
                        {
                            "id": 77,
                            "name": "Age Groups",
                            "slug": "age-groups",
                            "organizations_count": 0,
                            "services_count": 0,
                            "select_order": null,
                            "imported": false,
                            "is_core": false,
                            "show_on_homepage": false,
                            "account_id": null,
                            "parent_id": 75,
                            "lft": 152,
                            "rgt": 153,
                            "depth": 1,
                            "children_count": 0,
                            "created_at": "2019-03-01T18:17:41.851Z",
                            "updated_at": "2019-03-01T18:17:41.866Z"
                        },
                        {
                            "id": 76,
                            ...
                        }
                      ]