Documentation

Introduction

The GeoRocket API provides cities, counties, zip codes and country data.

Endpoint

All requests must use the following endpoint:

https://georocket.net/api/

Authentication

GeoRocket uses API tokens to allow access to the API.

All API requests to the server must include the following query parameter:

api_token=yourApiToken

For example:

https://georocket.net/api/cities?api_token=yourApiToken

Requests

All requests to the API must include the following HTTP Headers:

Accept: application/json;
Content-Type: applicaton/json;

Fields

All requests may include the fields parameter, which denotes the data that you want to have returned in the response. This is recommended for more complex queries on larger datasets, such as cities or zipcodes

JSON Key Description JSON Value Type Example JSON Value
fields Comma separated list of fields string Refer to each endpoint request below for applicable values, which can be found in the JSON Key column.
As the available data is regularly improving and increasing, it's recommended to perform your query without the fields parameter to see the available data. Then use the fields parameter to specify just the fields that you want for each result.

Database

All requests may include the database parameter, which denotes which database to query. This is useful for testing against a new import before it is moved to production.
If omitted, the mysql (production) database is queried.

JSON Key Description JSON Value Type Example JSON Value
database The database to query string mysql, mysql-import

Sorting

All requests may include the following parameters to sort results:

JSON Key Description JSON Value Type Example JSON Value
orderby Orders results by the given field string Refer to each endpoint request below for applicable values.
order Orders results either ascending or descending, based on the field in orderby string
  • ASC: Ascending (A to Z / Nearest to Furthest)
  • DESC: Descending (Z to A / Furthest to Nearest)

Rate Limits

Requests are limited to 60 per minute per API Token. This is subject to change at any time, and specific accounts may have different limits.

Errors

When a request fails, the following information is returned:

JSON Key Description JSON Value Type Example JSON Value
message Overall error message. string 
The given data was invalid.
errors Specific breakdown of error(s). object 
array:1 [
  "country" => array:1 [
    0 => "The country code is invalid."
  ]
]

Responses

GeoRocket returns data in JSON format, conforming to JSend

Zipcode Responses

JSON Key Description JSON Value Type Example JSON Value
status Whether the request was successful or not. string success,fail,error
data The response data. object Refer to each endpoint request below for applicable values.
links When more than 10000 results are available in a resultset, pagination links are provided. object 
array:2 [
  "next" => "https://georocket.net/api/zipcodes?start_id=2000"
  "prev" => "https://georocket.net/api/zipcodes?start_id=1000"
]
meta Associated metadata relating to the response, described above. object 
array:9 [
  "from" => "integer"
  "current_page" => "integer"
  "path" => "string"
  "per_page" => "integer"
  "to" => "integer"
  "has_more" => "boolean"
  "start_id" => "integer - the first result's ID"
  "end_id" => "integer - the last result's ID"
  "next_id" => "integer - the next ID to use as the start_id parameter for the next paginated request"
]

Non-Zipcode Responses

JSON Key Description JSON Value Type Example JSON Value
status Whether the request was successful or not. string success,fail,error
data The response data. object Refer to each endpoint request below for applicable values.
links When more than 10000 results are available in a resultset, pagination links are provided. object 
array:4 [
  "first" => "https://georocket.net/api/cities?page=1"
  "last" => "https://georocket.net/api/cities?page=50"
  "next" => "https://georocket.net/api/cities?page=2"
  "prev" => null
]
meta Associated metadata relating to the response, described above. object 
array:7 [
  "current_page" => "integer"
  "from" => "integer"
  "last_page" => "integer"
  "path" => "string"
  "per_page" => "integer"
  "to" => "integer"
  "total" => "integer"
]

GET Geocode

This endpoint returns a latitude and longitude for a given location.

HTTP Request

GET https://georocket.net/api/geocode

Query Parameters

Parameter Required Value Type(s) Description
Values in bold should be used where specified.
api_token Yes string Your API Token
location Yes string The location to return the latitude and longitude for. This must be in the format ZIP Code, Country Code or City, Country Code.

GET Phone Area Codes

This endpoint retrieves all Phone Area Codes, paginated, matching the given search parameters.

HTTP Request

GET https://georocket.net/api/phone_area_codes

Query Parameters

Parameter Required Value Type(s) Description
Values in bold should be used where specified.
api_token Yes string Your API Token
city_name No string or array of strings Return Phone Area Codes belonging to the given City Name(s).
Call the GET /cities endpoint for a list of valid Cities.
city_name_not No string or array of strings Return Phone Area Codes that do not belong to the given City Name(s).
Call the GET /cities endpoint for a list of valid Cities.
city_id No integer or array of integers Return Phone Area Codes belonging to the given City ID(s).
Call the GET /cities endpoint for a list of valid City IDs.
city_id_not No integer or array of integers Return Phone Area Codes that do not belong to the given City ID(s).
Call the GET /cities endpoint for a list of valid City IDs.
county_name No string or array of strings Return Phone Area Codes belonging to the given County Name(s).
Call the GET /counties endpoint for a list of valid Counties.
county_name_not No string or array of strings Return Phone Area Codes that do not belong to the given County Name(s).
Call the GET /counties endpoint for a list of valid Counties.
county_id No integer or array of integers Return Phone Area Codes belonging to the given County ID(s).
Call the GET /counties endpoint for a list of valid County IDs.
county_id_not No integer or array of integers Return Phone Area Codes that do not belong to the given County ID(s).
Call the GET /counties endpoint for a list of valid County IDs.
region_name No string or array of strings Return Phone Area Codes belonging to the given Region Name(s).
Call the GET /regions endpoint for a list of valid Regions.
region_name_not No string or array of strings Return Phone Area Codes that do not belong to the given Region Name(s).
Call the GET /regions endpoint for a list of valid Regions.
region_id No integer or array of integers Return Phone Area Codes belonging to the given Region ID(s).
Call the GET /regions endpoint for a list of valid Region IDs.
region_id_not No integer or array of integers Return Phone Area Codes that do not belong to the given Region ID(s).
Call the GET /regions endpoint for a list of valid Region IDs.
country_code No string Return Phone Area Codes belonging to the given ISO 3166-1 alpha-2 country code.
Call the GET /countries endpoint for a list of valid Country Codes.
country_name No string Return Phone Area Codes belonging to the given Country Name. For greater accuracy, consider using the country_code parameter above.
orderby No string Orders results by the given field
  • phone_area_code: Phone Area Code
  • city_name: City Name
  • county_name: County Name
  • region_name: Region Name
  • country_name: Country Name
  • country_code: Country Code
order No string Orders results either ascending or descending, based on the field in orderby
  • ASC: Ascending (A to Z / Nearest to Furthest)
  • DESC: Descending (Z to A / Furthest to Nearest)

GET Street Names

This endpoint retrieves all Street Names, paginated, matching the given search parameters.

HTTP Request

GET https://georocket.net/api/street_names

Query Parameters

Parameter Required Value Type(s) Description
Values in bold should be used where specified.
api_token Yes string Your API Token
street_name No string Return Street Names that match the given Street Name in part or in full.
Call the GET /street_names endpoint for a list of valid Street Names.
street_name_not No string Return Street Names that do not match to the given Street Name in part or in full.
Call the GET /street_names endpoint for a list of valid Street Names.
zipcode_district No string or array of strings Return Street Names that belong to the given Zipcode District.
Call the GET /zipcode_districts endpoint for a list of valid Zipcode Districts.
zipcode_district_not No string or array of strings Return Street Names that do not belong to the given Zipcode District.
Call the GET /zipcode_districts endpoint for a list of valid Zipcode Districts.
zipcode_district_id No integer or array of integers Return Street Names that belong to the given Zipcode District ID(s).
Call the GET /zipcode_districts endpoint for a list of valid Zipcode Districts.
zipcode_district_id_not No integer or array of integers Return Street Names that do not belong to the given Zipcode District ID(s).
Call the GET /zipcode_districts endpoint for a list of valid Zipcode Districts.
city_name No string or array of strings Return Street Names belonging to the given City Name(s).
Call the GET /cities endpoint for a list of valid Cities.
city_name_not No string or array of strings Return Street Names that do not belong to the given City Name(s).
Call the GET /cities endpoint for a list of valid Cities.
city_id No integer or array of integers Return Street Names belonging to the given City ID(s).
Call the GET /cities endpoint for a list of valid City IDs.
city_id_not No integer or array of integers Return Street Names that do not belong to the given City ID(s).
Call the GET /cities endpoint for a list of valid City IDs.
county_name No string or array of strings Return Street Names belonging to the given County Name(s).
Call the GET /counties endpoint for a list of valid Counties.
county_name_not No string or array of strings Return Street Names that do not belong to the given County Name(s).
Call the GET /counties endpoint for a list of valid Counties.
county_id No integer or array of integers Return Street Names belonging to the given County ID(s).
Call the GET /counties endpoint for a list of valid County IDs.
county_id_not No integer or array of integers Return Street Names that do not belong to the given County ID(s).
Call the GET /counties endpoint for a list of valid County IDs.
region_name No string or array of strings Return Cities belonging to the given Region Name(s).
Call the GET /regions endpoint for a list of valid Regions.
region_name_not No string or array of strings Return Street Names that do not belong to the given Region Name(s).
Call the GET /regions endpoint for a list of valid Regions.
region_id No integer or array of integers Return Street Names belonging to the given Region ID(s).
Call the GET /regions endpoint for a list of valid Region IDs.
region_id_not No integer or array of integers Return Street Names that do not belong to the given Region ID(s).
Call the GET /regions endpoint for a list of valid Region IDs.
country_code No string Return Street Names belonging to the given ISO 3166-1 alpha-2 country code.
Call the GET /countries endpoint for a list of valid Country Codes.
country_name No string Return Street Names belonging to the given Country Name. For greater accuracy, consider using the country_code parameter above.
orderby No string Orders results by the given field
  • street_name: Street Name
  • city_name: City Name
  • county_name: County Name
  • region_name: Region Name
  • country_name: Country Name
  • country_code: Country Code
order No string Orders results either ascending or descending, based on the field in orderby
  • ASC: Ascending (A to Z / Nearest to Furthest)
  • DESC: Descending (Z to A / Furthest to Nearest)

GET Zipcode Districts

This endpoint retrieves all Zipcode Districts, paginated, matching the given search parameters.

HTTP Request

GET https://georocket.net/api/zipcode_districts

Query Parameters

Parameter Required Value Type(s) Description
Values in bold should be used where specified.
api_token Yes string Your API Token
zipcode_district No string or array of strings Return Zipcode Districts that belong to the given Zipcode District.
Call the GET /zipcode_districts endpoint for a list of valid Zipcode Districts.
zipcode_district_not No string or array of strings Return Zipcode Districts that do not belong to the given Zipcode District.
Call the GET /zipcode_districts endpoint for a list of valid Zipcode Districts.
city_name No string or array of strings Return Zipcode Districts belonging to the given City Name(s).
Call the GET /cities endpoint for a list of valid Cities.
city_name_not No string or array of strings Return Zipcode Districts that do not belong to the given City Name(s).
Call the GET /cities endpoint for a list of valid Cities.
city_id No integer or array of integers Return Zipcode Districts belonging to the given City ID(s).
Call the GET /cities endpoint for a list of valid City IDs.
city_id_not No integer or array of integers Return Zipcode Districts that do not belong to the given City ID(s).
Call the GET /cities endpoint for a list of valid City IDs.
county_name No string or array of strings Return Zipcode Districts belonging to the given County Name(s).
Call the GET /counties endpoint for a list of valid Counties.
county_name_not No string or array of strings Return Zipcode Districts that do not belong to the given County Name(s).
Call the GET /counties endpoint for a list of valid Counties.
county_id No integer or array of integers Return Zipcode Districts belonging to the given County ID(s).
Call the GET /counties endpoint for a list of valid County IDs.
county_id_not No integer or array of integers Return Zipcode Districts that do not belong to the given County ID(s).
Call the GET /counties endpoint for a list of valid County IDs.
region_name No string or array of strings Return Zipcode Districts belonging to the given Region Name(s).
Call the GET /regions endpoint for a list of valid Regions.
region_name_not No string or array of strings Return Zipcode Districts that do not belong to the given Region Name(s).
Call the GET /regions endpoint for a list of valid Regions.
region_id No integer or array of integers Return Zipcode Districts belonging to the given Region ID(s).
Call the GET /regions endpoint for a list of valid Region IDs.
region_id_not No integer or array of integers Return Zipcode Districts that do not belong to the given Region ID(s).
Call the GET /regions endpoint for a list of valid Region IDs.
country_code No string Return Zipcode Districts belonging to the given ISO 3166-1 alpha-2 country code.
Call the GET /countries endpoint for a list of valid Country Codes.
country_name No string Return Zipcode Districts belonging to the given Country Name. For greater accuracy, consider using the country_code parameter above.
orderby No string Orders results by the given field
  • zipcode_district: Zipcode District
  • city_name: City Name
  • county_name: County Name
  • region_name: Region Name
  • country_name: Country Name
  • country_code: Country Code
order No string Orders results either ascending or descending, based on the field in orderby
  • ASC: Ascending (A to Z / Nearest to Furthest)
  • DESC: Descending (Z to A / Furthest to Nearest)

GET ZIP Codes

This endpoint retrieves all ZIP Codes (Postal Codes), paginated, matching the given search parameters.

HTTP Request

GET https://georocket.net/api/zipcodes

Query Parameters

For performance, order and orderby parameters are not accepted for zipcode requests. Results are ordered by database table row ID, and a next_id is included in the metadata response. This can be used to offset results, where there are more available results than the number returned. Refer to the Pagination section above for more information.
Parameter Required Value Type(s) Description
Values in bold should be used where specified.
api_token Yes string Your API Token
location Yes, if radius is defined. string Return ZIP Codes which fall within the given location and radius. Location can be freeform text, comprising of City, County, and/or ZIP Code.
radius Yes, if location is defined. integer (miles) Return ZIP Codes within the given radius of the above Location.
city_name No string or array of strings Return ZIP Codes belonging to the given City Name(s).
Call the GET /cities endpoint for a list of valid Cities.
city_name_not No string or array of strings Return ZIP Codes that do not belong to the given City Name(s).
Call the GET /cities endpoint for a list of valid Cities.
city_id No integer or array of integers Return ZIP Codes belonging to the given City ID(s).
Call the GET /cities endpoint for a list of valid City IDs.
city_id_not No integer or array of integers Return ZIP Codes that do not belong to the given City ID(s).
Call the GET /cities endpoint for a list of valid City IDs.
county_name No string or array of strings Return ZIP Codes belonging to the given County Name(s).
Call the GET /counties endpoint for a list of valid Counties.
county_name_not No string or array of strings Return ZIP Codes that do not belong to the given County Name(s).
Call the GET /counties endpoint for a list of valid Counties.
county_id No integer or array of integers Return ZIP Codes belonging to the given County ID(s).
Call the GET /counties endpoint for a list of valid County IDs.
county_id_not No integer or array of integers Return ZIP Codes that do not belong to the given County ID(s).
Call the GET /counties endpoint for a list of valid County IDs.
region_name No string or array of strings Return ZIP Codes belonging to the given Region Name(s).
Call the GET /regions endpoint for a list of valid Regions.
region_name_not No string or array of strings Return ZIP Codes that do not belong to the given Region Name(s).
Call the GET /regions endpoint for a list of valid Regions.
region_id No integer or array of integers Return ZIP Codes belonging to the given Region ID(s).
Call the GET /regions endpoint for a list of valid Region IDs.
region_id_not No integer or array of integers Return ZIP Codes that do not belong to the given Region ID(s).
Call the GET /regions endpoint for a list of valid Region IDs.
country_code No string Return ZIP Codes belonging to the given ISO 3166-1 alpha-2 country code.
Call the GET /countries endpoint for a list of valid Country Codes.
country_name No string Return ZIP Codes belonging to the given Country Name. For greater accuracy, consider using the country_code parameter above.

GET Cities

This endpoint retrieves all Cities, paginated, matching the given search parameters.

HTTP Request

GET https://georocket.net/api/cities

Query Parameters

Parameter Required Value Type(s) Description
Values in bold should be used where specified.
api_token Yes string Your API Token
location Yes, if radius is defined. string Return Cities which fall within the given location and radius. Location can be freeform text, comprising of City, County, and/or ZIP Code.
radius Yes, if location is defined. integer (miles) Return Cities within the given radius of the above Location.
population_min No integer Return Cities with a population greater than or equal to the given value.
population_max No integer Return Cities with a population less than or equal to the given value.
population_children_min No integer Return Cities with a population of children (under 18 years of age) greater than or equal to the given value.
population_children_max No integer Return Cities with a population of children (under 18 years of age) less than or equal to the given value.
population_children_percent_min No integer Return Cities with a population percentage of children (under 18 years of age) greater than or equal to the given value.
population_children_percent_max No integer Return Cities with a population percentage of children (under 18 years of age) less than or equal to the given value.
population_adults_min No integer Return Cities with a population of adults (18 to 64 years of age) greater than or equal to the given value.
population_adults_max No integer Return Cities with a population of adults (18 to 64 years of age) less than or equal to the given value.
population_adults_percent_min No integer Return Cities with a population percentage of adults (18 to 64 years of age) greater than or equal to the given value.
population_adults_percent_max No integer Return Cities with a population percentage of adults (18 to 64 years of age) less than or equal to the given value.
population_elderly_min No integer Return Cities with a population of elderly (65+ years of age) greater than or equal to the given value.
population_elderly_max No integer Return Cities with a population of elderly (65+ years of age) less than or equal to the given value.
population_elderly_percent_min No integer Return Cities with a population percentage of elderly (65+ years of age) greater than or equal to the given value.
population_elderly_percent_max No integer Return Cities with a population percentage of elderly (65+ years of age) less than or equal to the given value.
population_male_min No integer Return Cities with a population of men greater than or equal to the given value.
population_male_max No integer Return Cities with a population of men less than or equal to the given value.
population_male_percent_min No integer Return Cities with a population percentage of men greater than or equal to the given value.
population_male_percent_max No integer Return Cities with a population percentage of men less than or equal to the given value.
population_female_min No integer Return Cities with a population of women greater than or equal to the given value.
population_female_max No integer Return Cities with a population of women less than or equal to the given value.
population_female_percent_min No integer Return Cities with a population percentage of women greater than or equal to the given value.
population_female_percent_max No integer Return Cities with a population percentage of women less than or equal to the given value.
median_household_income_min No integer Return Cities with a median household income greater than or equal to the given value.
median_household_income_max No integer Return Cities with a median household income less than or equal to the given value.
city_name No string Return Cities that match the given City Name in part or in full.
Call the GET /cities endpoint for a list of valid Cities.
city_name_not No string Return Cities that do not match to the given City Name in part or in full.
Call the GET /cities endpoint for a list of valid Cities.
county_name No string or array of strings Return Cities belonging to the given County Name(s).
Call the GET /counties endpoint for a list of valid Counties.
county_name_not No string or array of strings Return Cities that do not belong to the given County Name(s).
Call the GET /counties endpoint for a list of valid Counties.
county_id No integer or array of integers Return Cities belonging to the given County ID(s).
Call the GET /counties endpoint for a list of valid County IDs.
county_id_not No integer or array of integers Return Cities that do not belong to the given County ID(s).
Call the GET /counties endpoint for a list of valid County IDs.
region_name No string or array of strings Return Cities belonging to the given Region Name(s).
Call the GET /regions endpoint for a list of valid Regions.
region_name_not No string or array of strings Return Cities that do not belong to the given Region Name(s).
Call the GET /regions endpoint for a list of valid Regions.
region_id No integer or array of integers Return Cities belonging to the given Region ID(s).
Call the GET /regions endpoint for a list of valid Region IDs.
region_id_not No integer or array of integers Return Cities that do not belong to the given Region ID(s).
Call the GET /regions endpoint for a list of valid Region IDs.
country_code No string Return Cities belonging to the given ISO 3166-1 alpha-2 country code.
Call the GET /countries endpoint for a list of valid Country Codes.
country_name No string Return Cities belonging to the given Country Name. For greater accuracy, consider using the country_code parameter above.
orderby No string Orders results by the given field
  • city_name: City Name
  • county_name: County Name
  • region_name: Region Name
  • country_name: Country Name
  • country_code: Country Code
  • distance: Available if location and radius parameters are included in a request.
order No string Orders results either ascending or descending, based on the field in orderby
  • ASC: Ascending (A to Z / Nearest to Furthest)
  • DESC: Descending (Z to A / Furthest to Nearest)

GET Counties

This endpoint retrieves all Counties, paginated, matching the given search parameters.

HTTP Request

GET https://georocket.net/api/counties

Query Parameters

Parameter Required Value Type(s) Description
Values in bold should be used where specified.
api_token Yes string Your API Token
county_name No string Return Counties that match the given County Name in part or in full.
Call the GET /counties endpoint for a list of valid Counties.
county_name_not No string Return Counties that do not match the given County Name in part or in full.
Call the GET /counties endpoint for a list of valid Counties.
region_name No string or array of strings Return Counties belonging to the given Region Name(s).
Call the GET /regions endpoint for a list of valid Regions.
region_name_not No string or array of strings Return Counties that do not belong to the given Region Name(s).
Call the GET /regions endpoint for a list of valid Regions.
region_id No integer or array of integers Return Counties belonging to the given Region ID(s).
Call the GET /regions endpoint for a list of valid Region IDs.
region_id_not No integer or array of integers Return Counties that do not belong to the given Region ID(s).
Call the GET /regions endpoint for a list of valid Region IDs.
country_code No string Return Counties belonging to the given ISO 3166-1 alpha-2 country code.
Call the GET /countries endpoint for a list of valid Country Codes.
country_name No string Return Counties belonging to the given Country Name. For greater accuracy, consider using the country_code parameter above.
orderby No string Orders results by the given field
  • county_name: County Name
  • region_name: Region Name
  • country_name: Country Name
  • country_code: Country Code
order No string Orders results either ascending or descending, based on the field in orderby
  • ASC: Ascending (A to Z / Nearest to Furthest)
  • DESC: Descending (Z to A / Furthest to Nearest)

GET Regions

This endpoint retrieves all Regions (States / Areas), paginated, matching the given search parameters.

HTTP Request

GET https://georocket.net/api/regions

Query Parameters

Parameter Required Value Type(s) Description
Values in bold should be used where specified.
api_token Yes string Your API Token
region_name No string Return Regions that match the given Region Name in part or in full.
region_name_not No string Return Regions that do not match the given Region Name in part or in full.
country_code No string Return Regions belonging to the given ISO 3166-1 alpha-2 country code.
Call the GET /countries endpoint for a list of valid Country Codes.
country_name No string Return Regions belonging to the given Country Name. For greater accuracy, consider using the country_code parameter above.
orderby No string Orders results by the given field
  • region_name: Region Name
  • country_name: Country Name
  • country_code: Country Code
order No string Orders results either ascending or descending, based on the field in orderby
  • ASC: Ascending (A to Z / Nearest to Furthest)
  • DESC: Descending (Z to A / Furthest to Nearest)

GET Countries

This endpoint retrieves all Countries, paginated, matching the given search parameters.

HTTP Request

GET https://georocket.net/api/countries

Query Parameters

Parameter Required Value Type(s) Description
Values in bold should be used where specified.
api_token Yes string Your API Token
country_name No string Return Countries that match the given Country Name in part or in full.
orderby No string Orders results by the given field
  • country_name: Country Name
  • country_code: Country Code
order No string Orders results either ascending or descending, based on the field in orderby
  • ASC: Ascending (A to Z / Nearest to Furthest)
  • DESC: Descending (Z to A / Furthest to Nearest)