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:
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:
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
Number of results to retrieve (default = 10, max = 50)
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 abbreviation
Choices: AZ CO ID MT WY
Number of results to retrieve (default = 10, max = 50)
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
Number of results to retrieve (default = 10, max = 50)
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
Full name of county
Number of results to retrieve (default = 10, max = 50)
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 abbreviation
Choices: AZ CO ID MT WY
Number of results to retrieve (default = 10, max = 50)
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 abbreviation
Choices: AZ CO ID MT WY
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 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
Full name of county
Number of results to retrieve (default = 10, max = 50)
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 abbreviation
Choices: AZ CO ID MT WY
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
Full name of county
Number of results to retrieve (default = 10, max = 50)
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
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
Number of results to retrieve (default = 10, max = 50)
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 abbreviation
Choices: AZ CO ID MT WY
Specific hunt code if known
UUID of specific unit
Specific year or years comma delimited
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
Species of deer if known - not all records apply
Manner of take
Choices: F A M SR P R SG Any SC HAM
Number of results to retrieve (default = 10, max = 50)
Get a specific page of results (default = 1)
Harvest
Get harvest details for a specific hunt.
Get a Harvest
GET /harvests/{id}
Examples
Parameters
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
Number of results to retrieve (default = 10, max = 50)
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 abbreviation
Choices: AZ CO ID MT WY
Specific hunt code if known
UUID of specific unit
Specific year or years comma delimited
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
Species of deer if known - not all records apply
Manner of take
Choices: F A M SR P R SG Any SC HAM
Number of results to retrieve (default = 10, max = 50)
Get a specific page of results (default = 1)
Drawing
Get drawing details for a specific hunt.
Get a Drawing
GET /drawings/{id}
Examples
Parameters
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
Number of results to retrieve (default = 10, max = 50)
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 abbreviation
Choices: AZ CO ID MT WY
County name within state
UUID of specific unit
Specific year or years comma delimited
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
Species of deer if known - not all records apply
Manner of take
Choices: F A M SR P R SG Any SC HAM
Number of results to retrieve (default = 10, max = 50)
Get a specific page of results (default = 1)
Record
Get records details for a specific record.
Get a Record
GET /records/{id}
Examples
Parameters
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
Number of results to retrieve (default = 10, max = 50)
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 abbreviation
Choices: AZ CO ID MT WY
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
Number of results to retrieve (default = 10, max = 50)
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
Number of results to retrieve (default = 10, max = 50)
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 abbreviation
Choices: AZ CO ID MT WY
UUID of specific unit
Number of results to retrieve (default = 10, max = 50)
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
Number of results to retrieve (default = 10, max = 50)
Get a specific page of results (default = 1)
Post
Get a specific blog post.
Get a Post
GET /posts/{id}
Examples
Parameters
slug of specific post
For Search
Returns search results for units, drawings, dates, and maps.
Query
Get a list of all search results.
Get All Search Results
GET /search/{?query}
Examples
Parameters
Number of results to retrieve (default = 10, max = 50)
Get a specific page of results (default = 1)
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
Number of results to retrieve (default = 10, max = 50)
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 abbreviation
Choices: AZ CO ID MT WY
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
What type of tip?
Choices: unit harvest drawing
Number of results to retrieve (default = 10, max = 50)
Get a specific page of results (default = 1)