@lap v0.3
# Machine-readable API spec. Each @endpoint block is one API call.
@api BC Geographical Names Web Service - REST API
@base https://apps.gov.bc.ca/pub/bcgnws
@version 3.x.x
@endpoints 14
@toc names(9), features(1), featureClasses(1), featureCategories(1), featureTypes(1), nameAuthorities(1)

@group names
@endpoint GET /names/search
@desc Search by name
@required {outputFormat: str(json/xml/kml/csv)=json # The format of the output., name: str # A filter to search based on the the text of the name itself.  Use the asterisk (*) as a wildcard character.  For example 'vancouv*'}
@optional {exactSpelling: int(0/1)=0 # If the 'name' parameter is specified, 'exactSpelling' specifies whether to include only names that exactly match the search text (exactSpelling=1), or whether to also include names with similar spellings (exactSpelling=0), featureClass: str=* # A filter to limit the search to names associated with features of a certain 'class'  The value of this parameter should be a 'featureClassCode' value returned by the /featureClasses resource, or an asterisk (*) to request that all feature classes be included., featureCategory: str=* # A filter to limit the search to names associated with features of a certain 'category'  The value of this parameter should be a 'featureCategoryCode' value returned by the /featureCategories resource, or an asterisk (*) to request that all feature categories be included., featureType: str=* # A filter to limit the search to names associated with features of a certain 'type'  The value of this parameter should be a 'featureTypeCode' value returned by the /featureTypes resource, or an asterisk (*) to request that all feature types be included, sortBy: str(relevance/name/featureType/decisionDate)=relevance # The distance to move the accessPoint away from the curb and towards the inside of the parcel (in metres). Ignored if locationDescriptor not set to accessPoint., outputSRS: int(4326/4269/3005/3857/26907/26908/26909/26910/26911)=4326 # The EPSG code of the spatial reference system (SRS) to use for output geometries., embed: int(0/1) # A flag to indicate whether to embed the corresponding 'feature' into each matching name, outputStyle: str(summary/detail)=summary # A flag indicating whether to include with each matching name a succinct list of attributes (summary), or a comprehensive list of attributes (detail), itemsPerPage: int=20 # The number of search results to return (1-200), startIndex: int=1 # The index of the first record to be returned (>= 1)}
@returns(200) A list of names matching the search criteria
@errors {400: A required parameter is missing or invalid}

@endpoint GET /names/official/search
@desc Search by name, limit to official names only
@required {outputFormat: str(json/xml/kml/csv)=json # The format of the output., name: str # A filter to search based on the the text of the name itself.  Use the asterisk (*) as a wildcard character.  For example 'vancouv*'}
@optional {exactSpelling: int(0/1)=0 # If the 'name' parameter is specified, 'exactSpelling' specifies whether to include only names that exactly match the search text (exactSpelling=1), or whether to also include names with similar spellings (exactSpelling=0), featureClass: str=* # A filter to limit the search to names associated with features of a certain 'class'  The value of this parameter should be a 'featureClassCode' value returned by the /featureClasses resource, or an asterisk (*) to request that all feature classes be included., featureCategory: str=* # A filter to limit the search to names associated with features of a certain 'category'  The value of this parameter should be a 'featureCategoryCode' value returned by the /featureCategories resource, or an asterisk (*) to request that all feature categories be included., featureType: str=* # A filter to limit the search to names associated with features of a certain 'type'  The value of this parameter should be a 'featureTypeCode' value returned by the /featureTypes resource, or an asterisk (*) to request that all feature types be included, sortBy: str(relevance/name/featureType/decisionDate)=relevance # The distance to move the accessPoint away from the curb and towards the inside of the parcel (in metres). Ignored if locationDescriptor not set to accessPoint., outputSRS: int(4326/4269/3005/3857/26907/26908/26909/26910/26911)=4326 # The EPSG code of the spatial reference system (SRS) to use for output geometries., embed: int(0/1) # A flag to indicate whether to embed the corresponding 'feature' into each matching name, outputStyle: str(summary/detail)=summary # A flag indicating whether to include with each matching name a succinct list of attributes (summary), or a comprehensive list of attributes (detail), itemsPerPage: int=20 # The number of search results to return (1-200), startIndex: int=1 # The index of the first record to be returned (>= 1)}
@returns(200) A list of names matching the search criteria
@errors {400: A required parameter is missing or invalid}

@endpoint GET /names/notOfficial/search
@desc Search by name, limit to unofficial names only
@required {outputFormat: str(json/xml/kml/csv)=json # The format of the output., name: str # A filter to search based on the the text of the name itself.  Use the asterisk (*) as a wildcard character.  For example 'vancouv*'}
@optional {exactSpelling: int(0/1)=0 # If the 'name' parameter is specified, 'exactSpelling' specifies whether to include only names that exactly match the search text (exactSpelling=1), or whether to also include names with similar spellings (exactSpelling=0), featureClass: str=* # A filter to limit the search to names associated with features of a certain 'class'  The value of this parameter should be a 'featureClassCode' value returned by the /featureClasses resource, or an asterisk (*) to request that all feature classes be included., featureCategory: str=* # A filter to limit the search to names associated with features of a certain 'category'  The value of this parameter should be a 'featureCategoryCode' value returned by the /featureCategories resource, or an asterisk (*) to request that all feature categories be included., featureType: str=* # A filter to limit the search to names associated with features of a certain 'type'  The value of this parameter should be a 'featureTypeCode' value returned by the /featureTypes resource, or an asterisk (*) to request that all feature types be included, sortBy: str(relevance/name/featureType/decisionDate)=relevance # The distance to move the accessPoint away from the curb and towards the inside of the parcel (in metres). Ignored if locationDescriptor not set to accessPoint., outputSRS: int(4326/4269/3005/3857/26907/26908/26909/26910/26911)=4326 # The EPSG code of the spatial reference system (SRS) to use for output geometries., embed: int(0/1) # A flag to indicate whether to embed the corresponding 'feature' into each matching name, outputStyle: str(summary/detail)=summary # A flag indicating whether to include with each matching name a succinct list of attributes (summary), or a comprehensive list of attributes (detail), itemsPerPage: int=20 # The number of search results to return (1-200), startIndex: int=1 # The index of the first record to be returned (>= 1)}
@returns(200) A list of names matching the search criteria
@errors {400: A required parameter is missing or invalid}

@endpoint GET /names/inside
@desc Search in a geographic area
@required {outputFormat: str(json/xml/kml/csv)=json # The format of the output., bbox: str # A geographic bounding box defining the search area.  Must be specified as a string of the form 'minLongitude,minLatitude,maxLongitude,maxLatitude' (WGS84). e.g. -119,49,-118,50}
@optional {featureClass: str=* # A filter to limit the search to names associated with features of a certain 'class'  The value of this parameter should be a 'featureClassCode' value returned by the /featureClasses resource, or an asterisk (*) to request that all feature classes be included., featureCategory: str=* # A filter to limit the search to names associated with features of a certain 'category'  The value of this parameter should be a 'featureCategoryCode' value returned by the /featureCategories resource, or an asterisk (*) to request that all feature categories be included., featureType: str=* # A filter to limit the search to names associated with features of a certain 'type'  The value of this parameter should be a 'featureTypeCode' value returned by the /featureTypes resource, or an asterisk (*) to request that all feature types be included, sortBy: str(name/featureType/decisionDate)=name # The distance to move the accessPoint away from the curb and towards the inside of the parcel (in metres). Ignored if locationDescriptor not set to accessPoint., outputSRS: int(4326/4269/3005/3857/26907/26908/26909/26910/26911)=4326 # The EPSG code of the spatial reference system (SRS) to use for output geometries., embed: int(0/1) # A flag to indicate whether to embed the corresponding 'feature' into each matching name, outputStyle: str(summary/detail)=summary # A flag indicating whether to include with each matching name a succinct list of attributes (summary), or a comprehensive list of attributes (detail), itemsPerPage: int=20 # The number of search results to return (1-200), startIndex: int=1 # The index of the first record to be returned (>= 1)}
@returns(200) A list of names matching the search criteria
@errors {400: A required parameter is missing or invalid}

@endpoint GET /names/near
@desc Search near to a geographic point
@required {outputFormat: str(json/xml/kml/csv)=json # The format of the output., featurePoint: str # A geographic coordinate specifying the centre point of the search area.  Must be specified as a string of the form 'longitude,latitude' (WGS84).  e.g. -120,51, distance: str # A radius (in kilometres) around the centre point.}
@optional {featureClass: str=* # A filter to limit the search to names associated with features of a certain 'class'  The value of this parameter should be a 'featureClassCode' value returned by the /featureClasses resource, or an asterisk (*) to request that all feature classes be included., featureCategory: str=* # A filter to limit the search to names associated with features of a certain 'category'  The value of this parameter should be a 'featureCategoryCode' value returned by the /featureCategories resource, or an asterisk (*) to request that all feature categories be included., featureType: str=* # A filter to limit the search to names associated with features of a certain 'type'  The value of this parameter should be a 'featureTypeCode' value returned by the /featureTypes resource, or an asterisk (*) to request that all feature types be included, sortBy: str(name/featureType/decisionDate)=name # The distance to move the accessPoint away from the curb and towards the inside of the parcel (in metres). Ignored if locationDescriptor not set to accessPoint., outputSRS: int(4326/4269/3005/3857/26907/26908/26909/26910/26911)=4326 # The EPSG code of the spatial reference system (SRS) to use for output geometries., embed: int(0/1) # A flag to indicate whether to embed the corresponding 'feature' into each matching name, outputStyle: str(summary/detail)=summary # A flag indicating whether to include with each matching name a succinct list of attributes (summary), or a comprehensive list of attributes (detail), itemsPerPage: int=20 # The number of search results to return (1-200), startIndex: int=1 # The index of the first record to be returned (>= 1)}
@returns(200) A list of names matching the search criteria
@errors {400: A required parameter is missing or invalid}

@endpoint GET /names/decisions/recent
@desc Search for names affected by recent naming decision
@required {outputFormat: str(json/xml/kml/csv)=json # The format of the output., days: int=30 # The number of days used to define the time window of naming decisions to search.  The number is interpreted as searching for 'names affected by decisions within the last X days'.}
@optional {featureClass: str=* # A filter to limit the search to names associated with features of a certain 'class'  The value of this parameter should be a 'featureClassCode' value returned by the /featureClasses resource, or an asterisk (*) to request that all feature classes be included., featureCategory: str=* # A filter to limit the search to names associated with features of a certain 'category'  The value of this parameter should be a 'featureCategoryCode' value returned by the /featureCategories resource, or an asterisk (*) to request that all feature categories be included., featureType: str=* # A filter to limit the search to names associated with features of a certain 'type'  The value of this parameter should be a 'featureTypeCode' value returned by the /featureTypes resource, or an asterisk (*) to request that all feature types be included, sortBy: str(name/featureType/decisionDate)=name # The distance to move the accessPoint away from the curb and towards the inside of the parcel (in metres). Ignored if locationDescriptor not set to accessPoint., outputSRS: int(4326/4269/3005/3857/26907/26908/26909/26910/26911)=4326 # The EPSG code of the spatial reference system (SRS) to use for output geometries., embed: int(0/1) # A flag to indicate whether to embed the corresponding 'feature' into each matching name, outputStyle: str(summary/detail)=summary # A flag indicating whether to include with each matching name a succinct list of attributes (summary), or a comprehensive list of attributes (detail), itemsPerPage: int=20 # The number of search results to return (1-200), startIndex: int=1 # The index of the first record to be returned (>= 1)}
@returns(200) A list of names matching the search criteria
@errors {400: A required parameter is missing or invalid}

@endpoint GET /names/decisions/year
@desc Search for names affected by naming decisions in a given year
@required {outputFormat: str(json/xml/kml/csv)=json # The format of the output., year: int # The year in which to search for names affected by naming decisions'.}
@optional {featureClass: str=* # A filter to limit the search to names associated with features of a certain 'class'  The value of this parameter should be a 'featureClassCode' value returned by the /featureClasses resource, or an asterisk (*) to request that all feature classes be included., featureCategory: str=* # A filter to limit the search to names associated with features of a certain 'category'  The value of this parameter should be a 'featureCategoryCode' value returned by the /featureCategories resource, or an asterisk (*) to request that all feature categories be included., featureType: str=* # A filter to limit the search to names associated with features of a certain 'type'  The value of this parameter should be a 'featureTypeCode' value returned by the /featureTypes resource, or an asterisk (*) to request that all feature types be included, sortBy: str(name/featureType/decisionDate)=name # The distance to move the accessPoint away from the curb and towards the inside of the parcel (in metres). Ignored if locationDescriptor not set to accessPoint., outputSRS: int(4326/4269/3005/3857/26907/26908/26909/26910/26911)=4326 # The EPSG code of the spatial reference system (SRS) to use for output geometries., embed: int(0/1) # A flag to indicate whether to embed the corresponding 'feature' into each matching name, outputStyle: str(summary/detail)=summary # A flag indicating whether to include with each matching name a succinct list of attributes (summary), or a comprehensive list of attributes (detail), itemsPerPage: int=20 # The number of search results to return (1-200), startIndex: int=1 # The index of the first record to be returned (>= 1)}
@returns(200) A list of names matching the search criteria
@errors {400: A required parameter is missing or invalid}

@endpoint GET /names/changes
@desc Search for names with metadata changes in a given period
@required {outputFormat: str(json/xml/kml/csv)=json # The format of the output., fromDate: int # Defines the earliest date (YYYY-MM-DD format) of the change time window for the search, toDate: int # Defines the latest date (YYYY-MM-DD format) of the change time window for the search}
@optional {featureClass: str=* # A filter to limit the search to names associated with features of a certain 'class'  The value of this parameter should be a 'featureClassCode' value returned by the /featureClasses resource, or an asterisk (*) to request that all feature classes be included., featureCategory: str=* # A filter to limit the search to names associated with features of a certain 'category'  The value of this parameter should be a 'featureCategoryCode' value returned by the /featureCategories resource, or an asterisk (*) to request that all feature categories be included., featureType: str=* # A filter to limit the search to names associated with features of a certain 'type'  The value of this parameter should be a 'featureTypeCode' value returned by the /featureTypes resource, or an asterisk (*) to request that all feature types be included, sortBy: str(name/featureType/decisionDate)=name # The distance to move the accessPoint away from the curb and towards the inside of the parcel (in metres). Ignored if locationDescriptor not set to accessPoint., outputSRS: int(4326/4269/3005/3857/26907/26908/26909/26910/26911)=4326 # The EPSG code of the spatial reference system (SRS) to use for output geometries., embed: int(0/1) # A flag to indicate whether to embed the corresponding 'feature' into each matching name, outputStyle: str(summary/detail)=summary # A flag indicating whether to include with each matching name a succinct list of attributes (summary), or a comprehensive list of attributes (detail), itemsPerPage: int=20 # The number of search results to return (1-200), startIndex: int=1 # The index of the first record to be returned (>= 1)}
@returns(200) A list of names matching the search criteria
@errors {400: A required parameter is missing or invalid}

@endpoint GET /names/{nameId}.{outputFormat}
@desc Get a name by its nameId
@required {nameId: int # The unique identifier for a name, outputFormat: str(json/xml/kml/csv/html)=json # The format of the output.}
@returns(200) Information about the name with the specified nameId
@errors {404: The name with the given nameId doesn't exist, or the output format is invalid.}

@endgroup

@group features
@endpoint GET /features/{featureId}
@desc Get a feature by its featureId
@required {featureId: int # The unique identifier for a feature}
@returns(200) Information about the feature with the specified featureId (XML format only)
@errors {404: The feature with the given featureId doesn't exist}

@endgroup

@group featureClasses
@endpoint GET /featureClasses
@desc Get all feature classes
@required {outputFormat: str(json/xml)=json # The format of the output.}
@returns(200) A list of feature classes

@endgroup

@group featureCategories
@endpoint GET /featureCategories
@desc Get all feature categories
@required {outputFormat: str(json/xml)=json # The format of the output.}
@returns(200) A list of feature categories

@endgroup

@group featureTypes
@endpoint GET /featureTypes
@desc Get all feature types
@required {outputFormat: str(json/xml)=json # The format of the output.}
@returns(200) A list of feature types

@endgroup

@group nameAuthorities
@endpoint GET /nameAuthorities
@desc Get all name authorities
@required {outputFormat: str(json/xml)=json # The format of the output.}
@returns(200) A list of name authorities

@endgroup

@end