API Specification

An application programming interface (API) describes how software components can communicate with each other. Use the Kinsey Reporter API to obtain the data collected from the Kinsey Reporter mobile apps. Kinsey Reporter staff makes no effort to verify the accuracy of crowd-sourced reports.

Detail methods, as their name implies, give detailed information on a single object; these take one argument, a name or id number, after the method name like so: http://kinseyreporter.org/API/detail/survey/Sexual%20Fetish/.

List methods give brief information about many objects. They have no mandatory arguments, but some may take optional GET parameters to narrow down the list e.g.: http://kinseyreporter.org/API/list/reports?tag=whip%20fetish.

Do not submit more than one API request every 10 seconds.

This is a RESTful API, returning JSON objects in the response. All API calls are case-insensitive with respect to object [survey, question, tag] names, and must be URI-escaped (e.g. %20 for spaces).

Click on an API method below to learn more.

Parameters: None.
Returns: Names and id numbers for currently active surveys.
Example URL: http://kinseyreporter.org/API/list/surveys/
Example JSON Response:
{
"surveys": [
    {
        "text": "Unwanted Experience",
        "id": 2
    },
    {
        "text": "Female Hormonal Birth Control Use and Effects",
        "id": 7
    }
]
}
Parameters:
from The beginning of the time frame to search, specified as YYYY‑MM‑DD hh:mm:ss or YYYY‑MM‑DD.
to The end of the time frame to search, specified as above.
tag A tag name or id; restricts search to reports containing the given tag.
country An ISO two-letter country code; restricts search to reports originating from given country.
Returns: The list of criteria used for the actual search, and a list of reports that meet the specified criteria.
Notes:
  • Please note that either a tag must be specified, or a time frame of one week or less.
  • Queries that do not meet this requirement will have their time frames truncated to one week.
Example URL: http://kinseyreporter.org/API/list/reports/?tag=male%20victim&from=2012-06-02
Example JSON Response:
{
"search_params": [
    {
        "tag": {
            "text": "male victim", 
            "id": 64
        }
    }, 
    {
        "from": "2012-06-02"
    }
], 
"reports": [
    {
        "timestamp": "2012-07-20 13:10:17", 
        "location": {
            "city": null, 
            "state": "Emilia-Romagna", 
            "country": "IT"
        }, 
        "report_id": 51
    }, 
    {
        "timestamp": "2012-08-21 12:00:00", 
        "location": {
            "city": "Porlezza", 
            "state": "Lombardy", 
            "country": "IT"
        }, 
        "report_id": 358
    }, 
    {
        "timestamp": "2012-09-03 00:00:00", 
        "location": {
            "city": "Lexington", 
            "state": "Kentucky", 
            "country": "US"
        }, 
        "report_id": 768
    }
]
}
Argument: A survey name or id number.
Returns: Details about the survey object and its associated questions.
Example URL: http://kinseyreporter.org/API/detail/survey/Unwanted%20Experience/
Example JSON Response:
{
"survey": {
    "text": "Unwanted Experience", 
    "start_date": "2012-05-31 12:00:00", 
    "id": 2, 
    "end_date": "2050-12-31 12:00:00", 
    "instructions": null
}, 
"questions": [
    {
        "text": "Victim gender", 
        "id": 9
    }, 
    {
        "text": "Aggressor gender", 
        "id": 10
    }, 
    {
        "text": "Aggressor number", 
        "id": 11
    }, 
    {
        "text": "Victim age", 
        "id": 12
    }, 
    {
        "text": "Aggressor age", 
        "id": 13
    }, 
    {
        "text": "Unwanted behaviors", 
        "id": 14
    }, 
    {
        "text": "Setting", 
        "id": 15
    }, 
    {
        "text": "Reporting to authority", 
        "id": 16
    }, 
    {
        "text": "Aggressor relationship", 
        "id": 49
    }, 
    {
        "text": "Physical injury", 
        "id": 50
    }
]
}
Argument: A question name or id number.
Returns: Details about the question object and its associated survey and tags.
Example URL: http://kinseyreporter.org/API/detail/question/46/
Example JSON Response:
{
"survey": {
    "text": "Unwanted Experience", 
    "id": 2
}, 
"question": {
    "text": "Victim gender", 
    "id": 9, 
    "multiple_answer": true, 
    "description": "Pick all tags that apply."
}, 
"tags": [
    {
        "text": "male victim", 
        "id": 64
    }, 
    {
        "text": "female victim", 
        "id": 65
    }, 
    {
        "text": "transgender victim", 
        "id": 66
    }
]
}
Argument: A tag name or id number.
Returns: Details about the tag object and its associated survey and question.
Example URL: http://kinseyreporter.org/API/detail/tag/male%20victim/
Example JSON Response:
{
"survey": {
    "text": "Unwanted Experience", 
    "id": 2
}, 
"tag": {
    "text": "male victim", 
    "id": 64
}, 
"question": {
    "text": "Victim gender", 
    "id": 9
}
}
Argument: A report id number.
Returns: Details about the report object, including time, location, and all tags submitted in the report.
Example URL: http://kinseyreporter.org/API/detail/report/989/
Example JSON Response:
{
"timestamp": "2012-09-05 12:00:00", 
"report_id": 989, 
"location": {
    "city": "New York", 
    "state": "New York", 
    "country": "US"
}, 
"tags": [
    {
        "text": "young victim", 
        "id": 73
    }, 
    {
        "text": "middle aged aggressor", 
        "id": 78
    }, 
    {
        "text": "male aggressor", 
        "id": 67
    }, 
    {
        "text": "male victim", 
        "id": 64
    }, 
    {
        "text": "single aggressor", 
        "id": 70
    }, 
    {
        "text": "verbal sexual harassment", 
        "id": 81
    }, 
    {
        "text": "body touching", 
        "id": 82
    }, 
    {
        "text": "other unwanted behaviors", 
        "id": 278
    }, 
    {
        "text": "unwanted behavior not reported", 
        "id": 90
    }, 
    {
        "text": "unwanted public experience", 
        "id": 87
    }
]
}