API Documentation

Our Web API lets your applications fetch data from the HuntScore database.

Based on simple REST principles, our Web API endpoints return metadata in JSON format about states, units, drawings, harvests, and many other useful datasets directly from the HuntScore website.

About the Web API


Through the HuntScore Web API, your applications can retrieve and manage HuntScore content. The base address of the API is http://api.huntscore.com/1.0. There are several endpoints at that address, each with its own unique path. To access all data through the Web API, an application must get permission to access the data. Authorization is via the HuntScore Accounts service.

Requests


The HuntScore Web API is based on REST principles: data resources are accessed via standard HTTPS requests in UTF-8 format to an API endpoint. Where possible, the API strives to use appropriate HTTP verbs for each action:

GET
Used for retrieving resources.
POST
Used for creating resources.
PUT
Used for changing/replacing resources or collections.
DELETE
Used for deleting resources.

Rate Limiting


To make the API fast for everybody, rate limits apply. Rate limiting is applied on an application basis (based on client id), regardless of how many users are using it.

If you get status code 429, it means that you have sent too many requests. If this happens, have a look in the Retry-After header, where you will see a number displayed. This is the amount of seconds that you need to wait, before you can retry sending your requests.

Responses


All data is received as a JSON object.

Response Status Codes


The API uses the following response status codes, as defined in the RFC 2616 and RFC 6585:

200 OK
The request has succeeded. The client can read the result of the request in the body and the headers of the response.
400 Bad Request
The request could not be understood by the server due to malformed syntax. The message body will contain more information; see Error Details.
401 Unauthorized
The request requires user authentication or, if the request included authorization credentials, authorization has been refused for those credentials.
403 Forbidden
The server understood the request, but is refusing to fulfill it.
404 Not Found
The requested resource could not be found. This error can be due to a temporary or permanent condition.
429 Too Many Requests
Rate limiting has been applied.
500 Internal Server Error
You should never receive this error, but if you are unlucky enough to get one, please report it to us at [email protected].
502 Bad Gateway
The server was acting as a gateway or proxy and received an invalid response from the upstream server.
503 Service Unavailable
The server is currently unable to handle the request due to a temporary condition which will be alleviated after some delay. You can choose to resend the request again.

Error Details


Apart from the response code, unsuccessful responses return information about the error as an error JSON object containing the following information:

KEY VALUE TYPE VALUE DESCRIPTION status integer The HTTP status code (also returned in the response header; see Response Status Codes for more information). message string A short description of the cause of the error.

Authentication


We require applications to authenticate all of their requests with OAuth 2 authentication. This visibility allows us to prevent abusive behavior, and it also helps us to further understand how categories of applications are using the API. We apply this understanding to better meet the needs of developers as we continue to evolve the platform.

Unless you want to write your own, you'll probably want to use an OAuth client. Here are a few we've used. Maybe they'll be useful to you.

How to use these or get setup is beyond the scope of this document. So, you're on your own.

For STATES

Get all active states and related information. All U.S. states are stored in the API, however the methods listed below will only return the active states: the states with additional supporting hunting data. This is he highest level of data categorization.

ALL STATES

Get a list of active states and their related data.

Get All States

GET /states{?limit,page}

Examples

Parameters

limit
integer (optional) Example: 10
Number of results to retrieve (default = 10, max = 50)
page
integer (optional) Example: 2
Get a specific page of results (default = 1)

Single State

Get a single active state and its related data.

Get A State

GET /states/{state}{?limit,page}

Examples

Parameters

state
string (required) Example: CO
State abbreviation
Choices: AZ CO ID MT WY
limit
integer (optional) Example: 10
Number of results to retrieve (default = 10, max = 50)
page
integer (optional) Example: 2
Get a specific page of results (default = 1)

For Counties

Get all active counties and related information. All counties are stored in the API, however the methods listed below will only return those within active states: the states with additional supporting data.

All Counties

Get a list of active counties and their related data.

Get All Counties

GET /counties{?limit,page}

Examples

Parameters

limit
integer (optional) Example: 10
Number of results to retrieve (default = 10, max = 50)
page
integer (optional) Example: 2
Get a specific page of results (default = 1)

Counties By Name

Get a list of all “active” counties by name search.

Get Counties By Name

GET /counties/{county}{?limit,page}

Examples

Parameters

county
string (required) Example: Boulder
Full name of county
limit
integer (optional) Example: 10
Number of results to retrieve (default = 10, max = 50)
page
integer (optional) Example: 2
Get a specific page of results (default = 1)

Counties in State

Get list of counties within a specific state. Some states utilize county level data and some do not. Those that don’t use Units often make use of County data. Additionally, other data points rely on County information.

Get Counties in State

GET /states/{state}/counties{?limit,page}

Examples

Parameters

state
string (required) Example: CO
State abbreviation
Choices: AZ CO ID MT WY
limit
integer (optional) Example: 10
Number of results to retrieve (default = 10, max = 50)
page
integer (optional) Example: 2
Get a specific page of results (default = 1)

County

Get specific county details within a specific state.

Get County

GET /states/{state}/counties/{county}

Examples

Parameters

state
string (required) Example: CO
State abbreviation
Choices: AZ CO ID MT WY
county

For Units

Hunting unit data. Not all states utilize hunt units. For those that do this is the most granular data segment for that state. Harvests and Preference Point data apply to Units.

All Units

Get a list of all available hunt units. This is the base level, and every state has units.

Get All Units

GET /units{?species,county,limit,page}

Examples

Parameters

species
string (optional) Example: E
Species abbreviation
Choices: E D M ALL BG BI BD BS B CD DD MD WD CS C D W E L J M G A P S T H O I
county
string (required) Example: Boulder
Full name of county
limit
integer (optional) Example: 10
Number of results to retrieve (default = 10, max = 50)
page
integer (optional) Example: 2
Get a specific page of results (default = 1)

Units in State

Get a list of hunt units within a specific state.

Get Units in State

GET /states/{state}/units{?county,species,limit,page}

Examples

Parameters

state
string (required) Example: CO
State abbreviation
Choices: AZ CO ID MT WY
species
string (optional) Example: E
Species abbreviation
Choices: E D M ALL BG BI BD BS B CD DD MD WD CS C D W E L J M G A P S T H O I
county
string (required) Example: Boulder
Full name of county
limit
integer (optional) Example: 10
Number of results to retrieve (default = 10, max = 50)
page
integer (optional) Example: 2
Get a specific page of results (default = 1)

Unit

Get the details for a specific hunt unit.

Get a Unit

GET /units/{id}

Examples

Parameters

id
string (required) Example: 01750131-5a54-49a6-a7ad-ab5beb0ee436
UUID of specific unit

For Harvests

Game harvest data for specific hunt units.

All Harvests

Get a list of all harvest data.

Get All Harvests

GET /harvests{?limit,page}

Examples

Parameters

limit
integer (optional) Example: 10
Number of results to retrieve (default = 10, max = 50)
page
integer (optional) Example: 2
Get a specific page of results (default = 1)

Harvests in State

Get a list of all harvest data within a specific state.

Get Harvests in State

GET /state/{state}/harvests{?apply_for,unit,year,species,speciesdeer,manner,limit,page}

Examples

Parameters

state
string (required) Example: CO
State abbreviation
Choices: AZ CO ID MT WY
apply_for
string (optional) Example: GYNHF56
Specific hunt code if known
unit
string (required) Example: 01750131-5a54-49a6-a7ad-ab5beb0ee436
UUID of specific unit
year
string (optional) Example: 2012
Specific year or years comma delimited
species
string (optional) Example: E
Species abbreviation
Choices: E D M ALL BG BI BD BS B CD DD MD WD CS C D W E L J M G A P S T H O I
speciesdeer
string (optional) Example: MD
Species of deer if known - not all records apply
manner
string (optional) Example: A
Manner of take
Choices: F A M SR P R SG Any SC HAM
limit
integer (optional) Example: 10
Number of results to retrieve (default = 10, max = 50)
page
integer (optional) Example: 2
Get a specific page of results (default = 1)

Harvest

Get harvest details for a specific hunt.

Get a Harvest

GET /harvests/{id}

Examples

Parameters

id
string (required) Example: 01750131-5a54-49a6-a7ad-ab5beb0ee436
UUID of specific harvest

For Drawings

Limited license drawing summaries and data for specific hunts.

All Drawings

Get a list of all drawing data.

Get All Drawings

GET /drawings{?limit,page}

Examples

Parameters

limit
integer (optional) Example: 10
Number of results to retrieve (default = 10, max = 50)
page
integer (optional) Example: 2
Get a specific page of results (default = 1)

Drawings in State

Get a list of all drawing data within a specific state.

Get Drawings in State

GET /state/{state}/drawings{?apply_for,unit,year,species,speciesdeer,manner,limit,page}

Examples

Parameters

state
string (required) Example: CO
State abbreviation
Choices: AZ CO ID MT WY
apply_for
string (optional) Example: GYNHF56
Specific hunt code if known
unit
string (required) Example: 01750131-5a54-49a6-a7ad-ab5beb0ee436
UUID of specific unit
year
string (optional) Example: 2012
Specific year or years comma delimited
species
string (optional) Example: E
Species abbreviation
Choices: E D M ALL BG BI BD BS B CD DD MD WD CS C D W E L J M G A P S T H O I
speciesdeer
string (optional) Example: MD
Species of deer if known - not all records apply
manner
string (optional) Example: A
Manner of take
Choices: F A M SR P R SG Any SC HAM
limit
integer (optional) Example: 10
Number of results to retrieve (default = 10, max = 50)
page
integer (optional) Example: 2
Get a specific page of results (default = 1)

Drawing

Get drawing details for a specific hunt.

Get a Drawing

GET /drawings/{id}

Examples

Parameters

id
string (required) Example: 01750131-5a54-49a6-a7ad-ab5beb0ee436
UUID of specific drawing

For Records

Records of trophy animals.

All Records

Get a list of all record data.

Get All Records

GET /records{?limit,page}

Examples

Parameters

limit
integer (optional) Example: 10
Number of results to retrieve (default = 10, max = 50)
page
integer (optional) Example: 2
Get a specific page of results (default = 1)

Records in State

Get a list of all record data within a specific state.

Get Records in State

GET /state/{state}/records{?county,unit,year,species,species2,manner,limit,page}

Examples

Parameters

state
string (required) Example: CO
State abbreviation
Choices: AZ CO ID MT WY
county
string (optional) Example: Boulder
County name within state
unit
string (required) Example: 01750131-5a54-49a6-a7ad-ab5beb0ee436
UUID of specific unit
year
string (optional) Example: 2012
Specific year or years comma delimited
species
string (optional) Example: E
Species abbreviation
Choices: E D M ALL BG BI BD BS B CD DD MD WD CS C D W E L J M G A P S T H O I
species2
string (optional) Example: MD
Species of deer if known - not all records apply
manner
string (optional) Example: A
Manner of take
Choices: F A M SR P R SG Any SC HAM
limit
integer (optional) Example: 10
Number of results to retrieve (default = 10, max = 50)
page
integer (optional) Example: 2
Get a specific page of results (default = 1)

Record

Get records details for a specific record.

Get a Record

GET /records/{id}

Examples

Parameters

id
string (required) Example: 01750131-5a54-49a6-a7ad-ab5beb0ee436
UUID of specific record

For Dates

Important hunting and application deadline dates for various states.

All Dates

Show all upcoming dates for all states and species.

Get All Records

GET /dates{?limit,page}

Examples

Parameters

limit
integer (optional) Example: 10
Number of results to retrieve (default = 10, max = 50)
page
integer (optional) Example: 2
Get a specific page of results (default = 1)

Dates in State

Show all dates for a specific state

Get Dates in State

GET /states/{state}/dates{?species,limit,page}

Examples

Parameters

state
string (required) Example: CO
State abbreviation
Choices: AZ CO ID MT WY
species
string (optional) Example: E
Species abbreviation
Choices: E D M ALL BG BI BD BS B CD DD MD WD CS C D W E L J M G A P S T H O I
limit
integer (optional) Example: 10
Number of results to retrieve (default = 10, max = 50)
page
integer (optional) Example: 2
Get a specific page of results (default = 1)

For Photos

Photos of hunt units, trophies, or other user-submitted photos.

All Photos

Show all photos for all states.

Get All Photos

GET /photos{?limit,page}

Examples

Parameters

limit
integer (optional) Example: 10
Number of results to retrieve (default = 10, max = 50)
page
integer (optional) Example: 2
Get a specific page of results (default = 1)

Photos in State

Show all photos for a specific state (and unit)

Get Photos in State

GET /states/{state}/photos{?unit,limit,page}

Examples

Parameters

state
string (required) Example: CO
State abbreviation
Choices: AZ CO ID MT WY
unit
string (required) Example: 01750131-5a54-49a6-a7ad-ab5beb0ee436
UUID of specific unit
limit
integer (optional) Example: 10
Number of results to retrieve (default = 10, max = 50)
page
integer (optional) Example: 2
Get a specific page of results (default = 1)

For Posts

Endpoint to access blog posts

All Posts

Get all blog posts.

Get All Posts

GET /posts{?limit,page}

Examples

Parameters

limit
integer (optional) Example: 10
Number of results to retrieve (default = 10, max = 50)
page
integer (optional) Example: 2
Get a specific page of results (default = 1)

Post

Get a specific blog post.

Get a Post

GET /posts/{id}

Examples

Parameters

id
string (required) Example: understanding-the-arizona-hunt-draw-process
slug of specific post

For Scores

This are the endpoints available to acces score data.

Nothing yet.

For Tips

Endpoint to access HuntScore hunting tips. These are important hunting and application tips for various states and species.

All Tips

Get all hunting available tips.

Get All Tips

GET /tips{?limit,page}

Examples

Parameters

limit
integer (optional) Example: 10
Number of results to retrieve (default = 10, max = 50)
page
integer (optional) Example: 2
Get a specific page of results (default = 1)

Tips in State

Get available tips for a specific state.

Get Tips in State

GET /states/{state}/tips{?unit,limit,page}

Examples

Parameters

state
string (required) Example: CO
State abbreviation
Choices: AZ CO ID MT WY
species
string (optional) Example: E
Species abbreviation
Choices: E D M ALL BG BI BD BS B CD DD MD WD CS C D W E L J M G A P S T H O I
applies_to
string (optional) Example: unit
What type of tip?
Choices: unit harvest drawing
limit
integer (optional) Example: 10
Number of results to retrieve (default = 10, max = 50)
page
integer (optional) Example: 2
Get a specific page of results (default = 1)