KCB API V1

Data is available as JSON or CSV.

List of Endpoints

Quick Search

Accepts one string and matches it to any text found in the following fields:

Use an asterisk wildcard to match start (hall*), end (*hall) or middle (*hall*). Use an underscore wildcard for individual letters (h_ll). Use double quotes for an exact search ("hall"). Pass no string to return all data.

Advanced Search

Accepts any combination of up to 15 different arguments, each of which is joined with AND. Replace argument with 'null' if the search shouldn't include it.

  1. Place-name: Searches current and / or historical place-names (depending on the next argument). Uses the same wildcard characters as the quick search
  2. Name type: Specify 'current' or 'historical' to limit a search or 'all' to include both types
  3. Earliest Start Date: Limit by the earliest recorded start date. Either supply a single year (e.g. 1600) or a range of years (e.g. 1550-1650), or use the less-than sign for dates before (e.g. <1600) or a greater-than sign for dates after (e.g. >1599)
  4. Source ID: limit the search to a single source ID
  5. Source text: Searches both short and full titles. Wildcards can be used as with quick search
  6. Obsolete: Specify 'Y' to limit search to only include obsolete forms or 'N' to limit search to only include non-obsolete forms
  7. Linear: Specify 'Y' to limit search to only include linear forms or 'N' to limit search to only include non-linear forms.
  8. Parishes: Include the numeric IDs of one or more parishes separated by commas to limit a search to only the selected parishes. Multiple parishes are joined with 'OR'
  9. Codes: Include one or more place-name code separated by commas to limit a search to only these classification types
  10. NGR: specify a single grid reference. Wildcards can be used, as with 'quick search'
  11. Altitude: specify an exact altitude (e.g. 50) or a range (e.g. 25-100)
  12. Analysis: search the 'analysis' field. Wildcards can be used as with 'quick search'
  13. Element ID: limit the search to a single element ID
  14. Element text: Limit a search to text found in an element. Wildcards can be used as with 'quick search'
  15. Element language: specify the code for an element language to limit a search to this language.

Examples:

Search for historical forms that have an 'h' followed by any character followed by 'll' (e.g. 'hill', 'hall') and an earliest start date between 1400 and 1500 and are classified as either settlements or antiquity:

Search for placenames that appear in the source with ID 284 (Ainslie/Stewartry(The Stewartry of Kirkcudbright) ) that have a grid reference 'NX6__8__' and have an altitude between 100 and 200 metres:

Search for place-names that mention 'granite' in their analysis and are found in parishes with IDs 5,4,7 and 1 (BMC, BMG, CMI, CPH)

Search for place-names that have an element in the language 'SSE' that are classified as 'vegetation' or 'water':

Sources

Pass a string and return all sources that feature the string in the 'source' or 'fulltitle' field. Alternatively, pass a numeric ID to return the details of a single source. Primarily used for an 'autocomplete' feature, therefore no wildcards are allowed. Pass no string to return a complete list of sources that are in use.

Parishes

Return all of the parishes that are in use in the system. Can be used to get 'parish ID' for use in the advanced search.

Classification Codes

Return all of the classification codes that are in use. These can then be used in the advanced search.

Elements

Search for an element and / or an element language, pass no arguments to return all of the elements that are currently associated with a place-name in the system. Alternatively, pass a numeric element ID to return details for a specific element. This is primarily used to populate the autocomplete in the advnaced search so no wildcards can be passed.

Return all elements that have the characters 'ba' in them:

Return all elements of language 'SSE' that have the characters 'st' in them:

Return all elements of language 'en':

Return details for element with ID 1932:

Element Languages

Return data about all of the languages that are currently associated with place-names. Language codes can be used in the element data and advanced searches.

Map Pop-up

Pass the ID for one place-name and the fields used in map pop-ups are returned

Browse

Pass one of seven browse types (e.g. current place-name forms) to return each item and a count of the number of place-names that match the item:

  1. nameCurrent: A list of initial letters of current place-names and the number of place-names for each
  2. nameHistorical: A list of initial letters of historical forms and the number of place-names for each
  3. startDate: A list of the earliest start dates of each place-name and the number of place-names for each
  4. source: A list of every source associated with historical forms and the number of place-names for each
  5. parish: A list of every parish and the number of place-names associated with each
  6. code: A list of every classification code and the number of place-names associated with each

Record

Pass the ID for one place-name and all available data for the place-name is returned